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-analysis, c3-synthesizer) for comprehensive 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)
**/references/component-lifecycle.md - Provisioned status model (for Stage 2b)

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 2b: Detect Provisioned Components

Check if component has a provisioned version:

# Check for provisioned version
ls .c3/provisioned/c3-*/c3-XXX-*.md 2>/dev/null

If provisioned version exists:

AskUserQuestion:
  question: "Found provisioned design for this component at .c3/provisioned/... Implement from this design?"
  options:
    - "Yes - use provisioned design as starting point"
    - "No - start fresh (will supersede provisioned)"

On "Yes":

Load provisioned doc as starting point for analysis
ADR frontmatter: add implements: <provisioned-adr>
After implementation complete, promote provisioned docs

On "No":

Proceed with normal alter flow (fresh analysis)
After implementation, delete orphaned provisioned file
Update provisioned ADR: superseded-by: <this-adr> with note "Design not used"

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: The Three Categories

Load **/references/component-categories.md for the full Foundation vs Feature vs Ref rules.

Key rule: Components (Foundation/Feature) MUST have ## Code References. Refs must NOT. If you cannot name a concrete file, create a ref instead.

Promoting Provisioned Components

If implementing a provisioned component (detected in Stage 2b):

Move file:

mv .c3/provisioned/c3-X/c3-XXX.md .c3/c3-X/c3-XXX.md

Update frontmatter:

status: active    # Changed from provisioned
# Remove supersedes: field if present
# Remove adr: field (or update to implementation ADR)

Add Code References section pointing to implemented files

Note: The provisioned ADR is superseded by c3-adr-transition agent AFTER verification passes in Stage 7, not during execution. This ensures we don't mark the design as superseded if implementation fails verification.

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}

c3-alter