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:

**/references/skill-harness.md - Red flags and complexity rules
**/references/layer-navigation.md - How to traverse C3 docs
**/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:

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

Follow plan order:

Make change (doc or code)
Check for conflicts
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:

Check if ref-* exists for pattern
Update ref if pattern changes
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}