Code Writing

Phase 1: Preparation

1. Parse Requirements
   • Extract what needs to be built from user message or passed acceptance criteria
   • Clarify ambiguities — ask user if unclear
   • Formulate acceptance criteria (what "done" looks like)

2. Read Project Context (Graceful)

   Working on a task? Read all files listed in the task's "Context" section — it already specifies everything needed.

   Standalone (no task file)? Read (skip if missing):

   • .claude/skills/project-knowledge/references/project.md — project overview
   • .claude/skills/project-knowledge/references/architecture.md — system structure
   • .claude/skills/project-knowledge/references/patterns.md — project conventions

   Then read .claude/skills/project-knowledge/SKILL.md (if exists). Consider which domain-specific guides are relevant to your task and read those (e.g., architecture.md Data Model section for DB work, ux-guidelines.md for UI tasks).

   No project patterns? Apply baseline from universal-patterns.md — naming, error handling, structure.

3. Brainstorm Approaches (for non-trivial tasks)

   Skip this step if: single-file change, obvious fix, user gave exact implementation instructions.

   Do this step if: multiple valid approaches exist, architectural decision needed, new feature, unfamiliar area.

   Explore 2-3 implementation approaches before writing code:

   Approach	Pros	Cons	Complexity
   A: ...	...	...	Low/Med/High
   B: ...	...	...	Low/Med/High

   For each approach consider:

   • Does it follow existing project patterns?
   • How much code needs to change?
   • What breaks if it's wrong? (blast radius)
   • Testing difficulty?

   Pick the approach with clear reasoning. Default to simplest unless simplest has obvious drawbacks. If genuinely uncertain — present options to user, let them decide.

   This step prevents: over-engineering, wrong abstractions, rework after half-implementation.

4. Analyze & Review Approach

   Before coding, output your findings:

   • Grep for usages of code to be modified
   • Read all files that will be changed
   • Verify solution follows project patterns (or universal patterns)
   • Identify existing code that can be reused
   • If modifying existing code, run existing tests for the area to establish baseline
   • Reversibility check: Can changes be rolled back without data loss? For M/L features: consider feature flags for new behavior. For DB migrations: ensure rollback works. For external integrations: adapter pattern (easy to swap/disable). Principle: Adopt existing code > Adapt existing patterns > Invent new.

   If concerns → discuss with user before proceeding.

Checkpoint: List completed preparation steps (including chosen approach if brainstorm was done) before moving to implementation.

Phase 2: Implementation (TDD)

1. Write Tests First

   Before writing tests, read testing-guide.md — when to write which test type, test structure.

   • Write tests for: business logic, validations, transforms, error handling. Skip trivial code without logic (simple getters, one-liners, configs)
   • Write tests for requirements and edge cases
   • Run each new test before the implementation exists and read the failure. It fails on the missing behaviour: an assertion about a result the code does not yet produce, or the absence of the exact function you are about to add. A typo, a wrong import path or a broken fixture does not count; fix the test until it fails for the right reason.
   • One test = one scenario, test behavior not implementation
   • If mocking >3 dependencies → wrong test type, use integration test
2. Write Code
   • Implement to pass tests
   • Follow project patterns (from Phase 1) or apply baseline from universal-patterns.md
   • If tech-spec Complexity Classification is "Product": prefer simplest working solution, use existing patterns. New abstractions require explicit justification.
   • For risky integrations: wrap behind a toggle/config flag if feasible
   • Use env vars for secrets, validate inputs at boundaries
   • Handle edge cases, comment WHY not WHAT
3. Run Tests
   • All new tests pass
   • Fix any failures

Checkpoint: List implemented functionality and test results.

Phase 3: Post-work

1. Run Lint/Format
   • Run project's linter and formatter before reviews
2. Run Relevant Tests
   • Tests for files changed
   • Tests mentioned in task (if applicable)
   • Save full test suite for end of feature

3. Structural Gates (changed files only)

   If your changed files include Python, TS/JS, Go, Rust, Java or Clojure source, read quality-gates.md and run its three gates (complexity × coverage, duplication, mutation) on them. Each miss is fixed or carries a one-line reason; a gate that could not run goes into the report as not run, with the reason.

4. Smoke Verification (if task has Verification Steps → Smoke or User)

   Execute each command from the Smoke section. Record results in decisions.md Verification section. If a check fails — fix the code before proceeding to reviews. If the task has User checks — ask the user to verify, wait for confirmation.

   Smoke catches integration bugs that mocked tests miss: real API responses, library initialization, config validity.

5. Run Reviews (launch in parallel)

   Reviewer selection:

   • Working on a task file → run reviewers from the task's "Reviewers" section
   • Standalone (no task file) → default: code-reviewer, security-auditor, test-reviewer

   For each reviewer:

   1. Spawn subagent via Task tool (subagent_type = reviewer name, e.g. code-reviewer)
   2. Pass: git diff of changes, path to task file, path to tech-spec, path to user-spec
   3. Reviewer loads its own skill automatically (via agent frontmatter skills:)
   4. Report path: from the task's "Reviewers" section (or logs/working/ if standalone)

   Reviewers write JSON reports to logs/working/task-{N}/{reviewer-name}-{round}.json. {N} = task number from task file; "standalone" if no task file. On re-review: new file with incremented round number, old file stays.

6. Process Findings

   Evaluate each finding on merit — severity is metadata, not a filter. A valid minor fix still improves quality. Reason: skipping valid findings silently degrades the codebase over time.

   For each finding:

   • Valid, improves code → apply (any severity: critical, major, minor, low)
   • Disagree or uncertain → discuss with user (explain reasoning)
   • Out of scope → skip, note in findings log

   Produce a findings log: | # | Source | Severity | Finding | Action | Reason | Each finding appears in this table — transparent decision trail.

   After applying fixes → re-run tests → re-run the reviewer(s) that reported them. Limit: 3 review iterations. If findings remain after round 3 → ask user. Reason: fixes can introduce new issues — a second pass catches regressions.

Checkpoint: List post-work steps completed.

Self-Verification

Verify each item before marking complete. If any item fails, return to the relevant phase.

• All phases completed (Preparation, Implementation, Post-work)
• Tests pass
• Structural gates run on changed files, or reported as not run with the reason
• Smoke verification executed (if task had Smoke/User checks)
• Each reviewer finding evaluated and logged
• Findings log table produced
• Review JSON reports saved to logs/working/task-{N}/