pavel-molyanov/code-writing

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. 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

   If concerns → discuss with user before proceeding.

Checkpoint: List completed preparation steps 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
   • Tests should fail initially (no implementation yet)
   • 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
   • 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. 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.

4. 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.

5. 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
• [ ] 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}/