---

name: c3-alter description: | Makes architectural changes through ADR-first workflow with staged intent clarification. Use when the user asks to "add a component", "change architecture", "refactor X", "implement feature", "fix bug", "create new service", "update diagram", or "remove component". Requires .c3/ to exist. All changes flow through ADR process. For questions, route to c3-query instead.

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)

CopyANALYZE → 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:

CopyChange 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

---

Stage 2: Current State

---

Stage 3: Scope Impact

---

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.

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:

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

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.

---

Examples

Example 1: Add feature

CopyUser: "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

CopyUser: "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

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