Architecture Design

Design an architecture doc for a new feature, refactor, or redesign. Produces a doc in

docs/architecture/pending/

with complete file impact analysis.

Inputs

The user provides one of:

• A feature name or concept (e.g., "behavior mutations")
• A path to an issue doc (e.g.,

  docs/issues/002-behavior-mutations.md

  )
• A description of the problem to solve

Process

Checkpoint 1: Problem + Solution (wait for user approval)

1. Load context:

   • docs/CAPABILITIES.md

     — current capability status

   • docs/architecture/README.md

     — architecture overview + reading order
   • If user provided an issue path, read that too

2. Write Problem and Solution sections:

   • Problem: What's wrong or missing. Include a concrete example (config snippet, error, limitation).
   • Solution: High-level approach. One paragraph + diagram or YAML snippet.

3. Present to user for approval. Do not continue until they confirm the direction is right.

Automated Phase (after direction is approved)

4. Load relevant architecture docs per README.md reading order for the area being designed.

5. Read existing source code that the design touches. Use Grep/Glob/find_references to locate all relevant files.

6. Write remaining sections using the template at

   .claude/skills/arch-design/template.md

   :
   • Semantics — behavioral rules, edge cases, ordering, timing
   • Configuration — YAML examples if the feature has educator-facing config
   • Interface Contracts — function signatures with full docstrings
   • Validation Rules — parse-time (Pydantic) and business rules
   • Implementation Impact — the key section (see below)
   • What Doesn't Change — explicit scope boundaries

7. Build the Implementation Impact section:

   • Use Grep to find every import of types/functions being moved or modified
   • Use find_references for symbols being renamed or relocated
   • Use Glob to find test files that cover affected modules
   • For each file: action (Create/Modify), path, one-line description of change
   • Separate into: Source Files, Test Files, Import Updates
   • The Import Updates table must show current import → new import for every file affected by moves/renames

8. Write the complete doc to

   docs/architecture/pending/<name>.md

9. Present the full doc to user with a summary of:

   • Total files affected (create/modify counts)
   • Import sites found
   • Any design decisions that could go either way (flag for user)

Quality Rules

• No invented scenario values (Principle #7) — contracts must not introduce defaults for educator-specified parameters
• No future scaffolding (Principle #8) — design only what this feature needs, not extensibility for hypothetical future work
• Breaking changes are fine (Principle #9) — don't add compatibility shims
• Complete import tracing — every file that imports a moved/renamed symbol must appear in the Import Updates table. Use Grep for

  from module import symbol

  and

  import module

  patterns.
• Concrete contracts — every function signature includes Args, Returns, Raises. No

  ...

  bodies in the doc; show the signature and docstring only.
• Testable sections — Semantics section should use tables (Condition | Result) so sprint specs can derive test cases directly.
• No implementation code — design docs contain signatures and docstrings, never implementation bodies. Describe behavior in prose and tables, not code blocks with for-loops or if-statements. Wrong: showing the literal code to insert into

  processor.py

  . Right: "After

  execute_action()

  returns non-empty decisions, apply mutations and record history if tracked."
• No duplication with sprint specs — the design doc provides rationale, semantics, and constraints (the WHY). The sprint spec provides contracts, phases, and test cases (the WHAT). If a sprint spec will be written from this design doc, the sprint planner extracts contracts from here — don't write content that forces the planner to duplicate or filter.

Output Location

docs/architecture/pending/<feature-name>.md

The

pending/

directory holds designs that haven't been implemented yet. After sprint completion, move to

docs/architecture/

if the design becomes a permanent reference, or delete if it was consumed by the sprint spec.