Write Code

Write Code

Follow this workflow to deliver correct, minimal, and verified code changes.

1. Define the target before editing

• Restate requested behavior in concrete input and output terms.
• Define acceptance criteria that are testable.
• List assumptions that can be falsified by a command or test.
• Ask one targeted question only when blocked; provide a recommended default.

2. Discover authoritative context

• Read the closest tests first, then public interfaces and types, then implementation details.
• Find existing patterns with focused search (rg for symbols, file names, and config keys).
• Identify repository invariants: architecture boundaries, lint and type rules, and CI expectations.
• For non-trivial work (3+ steps, multi-file, behavior change), maintain tasks/todo.md with:
  • checklist steps
  • explicit verification tasks
  • risk level and rollback notes for medium or high risk
  • working notes for constraints, decisions, and pitfalls

3. Plan a minimal safe change

• Prefer the smallest change that satisfies acceptance criteria.
• Reuse existing abstractions and conventions before adding dependencies.
• Avoid drive-by refactors unless they materially reduce risk in the current task.
• Gate high-risk changes (auth, billing, migrations, secrets, deployment) behind a safe rollout strategy.

4. Implement in thin slices

• Implement one observable behavior slice at a time.
• Keep one step in progress and verify it before expanding scope.
• Preserve explicit control flow and readable naming.
• Stop immediately when unexpected failures appear; diagnose before adding more changes.

5. Add regression protection

• For bug fixes, reproduce first and add a failing test when feasible.
• Add the smallest test that would have caught the issue.
• Prefer:
  • unit tests for pure logic
  • integration tests for boundaries (database, network, queue)
  • e2e tests only for critical user flows
• Validate boundary inputs and error paths, not only happy paths.

6. Verify before declaring done

Run the highest relevant verification tier and record outcomes.

• Tier 1: targeted tests plus lint and typecheck
• Tier 2: integration tests plus deterministic local repro
• Tier 3: e2e or staging checks plus rollout monitoring signals (when applicable)

If any check cannot run, state why and provide exact commands to run later.

7. Report with evidence

Provide a concise diff-oriented summary:

• what changed
• what behavior changed and what stayed the same
• commands run and outcomes
• remaining risks, assumptions, and rollback notes (if applicable)

Reference concrete artifacts: file paths, test names, and command lines.

Optional parallelization

• Use focused subagents for repository discovery, failing test triage, and risk review.
• Require structured deliverables from subagents: files, symbols, constraints, and verification commands.

Guardrails

• Never invent paths, APIs, or config keys; verify in-repo before asserting.
• Never expose secrets in code, logs, or output.
• Fail loudly and safely when behavior cannot be proven.
• Prefer reversible changes and explicit diagnostics over silent fallback behavior.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.