C3 Alter - Change Through ADR

Every change flows through an ADR. No exceptions.

Relationship to c3-orchestrator agent: This skill defines the change workflow stages. The c3-skill:c3-orchestrator agent implements this workflow, dispatching to sub-agents (c3-analyzer, c3-impact, c3-patterns, c3-synthesizer) for parallel analysis. Use the agent when spawning via Task tool; use this skill directly for inline execution.

REQUIRED: Load References

Before proceeding, use Glob to find and Read these files:

1. **/references/skill-harness.md - Red flags and complexity rules
2. **/references/layer-navigation.md - How to traverse C3 docs
3. **/references/adr-template.md - ADR structure (for Stage 4)

Core Loop (All Stages)

ANALYZE → ASK (until confident) → SYNTHESIZE → REVIEW
              │                        │
              └── until no open ───────┘
                  questions

On conflict: ASCEND → fix earlier stage → re-descend

Confident = No open questions. Don't proceed with "TODO" or unclear fields.

Progress Checklist

Copy and track as you work:

Change Progress:
- [ ] Stage 1: Intent clarified (type, goal confirmed)
- [ ] Stage 2: Current state documented (affected components listed)
- [ ] Stage 3: Scope assessed (all c3 IDs, breaking changes noted)
- [ ] Stage 4: ADR created (proposed, validation passed)
- [ ] Stage 4b: ADR accepted by user
- [ ] Stage 5: Plan created with ordered steps
- [ ] Stage 6: Execution complete (docs, code, diagrams)
- [ ] Stage 7: Audit passed, ADR marked implemented

---

Stage 1: Intent

Step	Action
Analyze	Add/modify/remove/fix? What problem? Scope hint?
Ask	Use AskUserQuestion: feature vs fix? problem? urgency?
Synthesize	Intent: [action] Goal: [outcome] Type: [feature/fix/refactor]
Review	User confirms or corrects

---

Stage 2: Current State

Step	Action
Analyze	Read affected C3 docs via layer navigation
Ask	Are docs accurate? Recent code changes not documented?
Synthesize	List affected components, their current behavior, dependencies
Review	User confirms or corrects

---

Stage 3: Scope Impact

Step	Action
Analyze	Which layers change? Dependencies? Linkages? Diagrams?
Ask	External systems involved? Breaking changes? Keep or replace?
Synthesize	List all affected c3 IDs, note breaking changes
Review	User confirms or expands

---

Stage 4: Create ADR

Generate at .c3/adr/adr-YYYYMMDD-{slug}.md. Use **/references/adr-template.md.

Key sections: Problem, Decision, Rationale, Affected Layers, References Affected, Verification

Note: ADR is only created after synthesizer validation passes. The synthesizer validates architectural coherence before ADR generation.

---

Stage 4b: ADR Acceptance

Use AskUserQuestion to ask the user to approve or reject the ADR.

On Accept	Update status to accepted, then immediately execute Stage 5 and 6
On Reject	Return to Stage 1/3 based on what changed

CRITICAL - After user accepts ADR: You MUST continue executing without stopping. Create the component documentation file(s) and update the container README. Do NOT end after receiving approval.

---

Stage 5: Create Plan

Generate at .c3/adr/adr-YYYYMMDD-{slug}.plan.md.

Include:

• Pre-execution checklist (update ## References in affected components)
• Ordered steps: docs first, then code, then diagrams
• Verification commands

After ADR acceptance, immediately create the plan and continue to execution.

---

Stage 6: Execute

Execute the plan immediately after creating it. For documentation-only changes (no code implementation requested), this means:

1. Create component documentation - Write the new component file (e.g., c3-106-*.md)
2. Update container README - Add new component to the Components table
3. Update TOC - Add link to new component

Follow plan order:

1. Make change (doc or code)
2. Check for conflicts
3. Update ## References if code moved/added/removed

On conflict - Tiered response:

Impact	Action
High: scope expansion, breaking change, new layer	Ask user, update ADR if needed
Low: wording fix, diagram update, ID fix	Auto-fix, note in log

Ref Maintenance

If change affects a pattern:

1. Check if ref-* exists for pattern
2. Update ref if pattern changes
3. Create new ref if pattern is new and reusable

Critical: Components vs Refs

Documenting...	Use	Path
Code that runs	Component	.c3/c3-N-*/c3-NNN-*.md
Conventions/patterns	Ref	.c3/refs/ref-*.md

NEVER create component files for:

• Information architecture
• User flows
• Design systems
• UI patterns
• Error handling conventions
• Form patterns

These are refs, not components.

---

Stage 7: Verify

Run /c3 audit. Check diagrams, IDs, linkages, code-doc match.

On Pass	Update ADR status to implemented
On Fail	Fix issue, re-audit, loop until pass

---

Examples

Example 1: Add feature

User: "Add rate limiting to the API"

Stage 1 - Intent:
  Intent: Add rate limiting
  Goal: Prevent API abuse
  Type: Feature

Stage 2 - Current State:
  Affected: c3-2-api (API Backend)
  Current: No rate limiting exists
  Depends on: c3-201-auth-middleware (good injection point)

Stage 3 - Scope:
  Changes: Add c3-206-rate-limiter component
  Affects: c3-201 (middleware chain)
  Breaking: No

Stage 4 - ADR:
  Created: .c3/adr/adr-20260109-rate-limiting.md
  Status: proposed (validation passed)

Stage 4b - Accept:
  User accepts → status: accepted

Stage 5 - Plan:
  1. Create c3-206-rate-limiter.md
  2. Update c3-2-api/README.md inventory
  3. Implement src/api/middleware/rate-limiter.ts
  4. Update c3-201 hand-offs

Stage 6 - Execute: Follow plan
Stage 7 - Verify: /c3 audit

Example 2: Fix bug

User: "Fix the login timeout issue"

Stage 1 - Intent:
  Intent: Fix bug
  Goal: Login doesn't timeout prematurely
  Type: Fix

Stage 2 - Current State:
  Affected: c3-201-auth-middleware
  Current: Session TTL hardcoded to 15min
  Issue: Users report logout after 10min

Stage 3 - Scope:
  Changes: Modify existing component
  Affects: c3-201 only
  Breaking: No

Stage 4 - ADR:
  Created: .c3/adr/adr-20260109-login-timeout-fix.md
  Status: proposed (validation passed, simpler ADR for bugfix)

Stage 4b - Accept:
  User accepts → status: accepted

Stage 5-7: Execute and verify

---

Response Format

**Stage N: {Name}**
{findings}
**Open Questions:** {list or "None - confident"}
**Next:** {what happens next}