write-tech-spec

$27

Use this skill when the implementation spans multiple modules, has meaningful architectural tradeoffs, or when reviewers will benefit from seeing the plan before or alongside the code. For pure UI changes or straightforward fixes, a tech spec is often unnecessary.

Prefer to have a PRODUCT.md first so the technical plan is anchored to agreed behavior. If the implementation is still too uncertain, build an e2e prototype first and then write the tech spec from what was learned.

Research before writing

Before drafting, read the product spec (if any), inspect the relevant code, and identify the main files, types, data flow, and ownership boundaries. Do not guess about current architecture when the code can be inspected directly.

Structure

Required sections:

-

Context — What's being built, how the current system works in the area being changed, and the most relevant files with line references. Combine the "problem," "current state," and "relevant code" into one grounded section. Example references:

• app/src/workspace/mod.rs:42 — entry point for the user flow

• app/src/workspace/workspace.rs (120-220) — state and event handling that will likely change

Reference PRODUCT.md for user-visible behavior rather than restating it.

-

Proposed changes — The implementation plan: which modules change, new types/APIs/state being introduced, data flow, ownership boundaries, and how the design follows existing patterns. Call out tradeoffs when there is more than one reasonable path.

-

Testing and validation — How the implementation will be verified against the product behavior. Owns everything about proving the feature works: unit tests, integration tests, manual steps, screenshots, videos, and any other verification. Reference the numbered Behavior invariants from PRODUCT.md directly rather than restating them; each important invariant should map to a concrete test or verification step. This section is where validation lives — PRODUCT.md intentionally does not have a Validation section.

-

Parallelization — Actively evaluate whether parallel sub-agents (launched via run_agents) would meaningfully reduce wall-clock time or isolate work. Skip this section if run_agents is not available. When the spec proposes using sub-agents, include for each proposed agent:

• A short name/role and the subtask it owns.

• Execution mode (local or remote) with a one-line rationale.

• For local agents: the working directory or git worktree it should use, so parallel agents do not collide on the same checkout or files.

• For remote agents: which environment to use or an explicit note that the agent will run in an empty environment.

• Branch and PR strategy: which branch each agent works on, the worktree path each agent will use, and how their work lands (one PR per agent, a single combined PR, etc.).

• Coordination boundaries: which files/services each agent owns and how it syncs with sibling agents (messaging, merge points, validation ownership).

Distinguish which steps can run in parallel and which must run sequentially. When the dependency graph is non-trivial, consider a short Mermaid diagram (graph TD or flowchart LR) so the reader can see fan-out and merge points at a glance.

When parallelization is NOT proposed, briefly note why it isn't beneficial (e.g. the task is small, or subtasks are tightly coupled) so reviewers can challenge that judgment.

Propose concrete defaults for worktrees, branch names, and execution mode rather than leaving them open-ended.

Optional sections — include only when they add signal. Omit the heading entirely if empty; do not write "None" as a placeholder.

• End-to-end flow — Include only when tracing the path through the system tells you something the Proposed changes list doesn't.

• Diagram — Include a Mermaid diagram only when a visual will explain the design faster than prose (data flow, state transitions, sequence across layers). Prefer one or two focused diagrams over decorative ones.

• Risks and mitigations — Include when there are real failure modes, regressions, migration concerns, or rollout hazards worth calling out.

• Follow-ups — Include when there is deferred cleanup or future work worth naming.

Length heuristic

Right-size the spec to the feature:

• Single-file change with clear approach: skip the tech spec or keep it under ~40 lines.

• Multi-module change with some ambiguity: target ~80–150 lines.

• Large cross-cutting or architecturally novel change: longer is fine when every section earns its place.

If Context and Proposed changes end up describing the same files and state from different angles, collapse them.

Writing guidance

• Ground the plan in actual codebase structure and patterns.

• Prefer concrete implementation guidance over generic architecture language.

• Explain why the proposed design fits this repo.

• Reference PRODUCT.md for behavior instead of restating it.

• Each section should earn its place — if a section would repeat another or contain only boilerplate, omit it.

Keep the spec current

Approved specs may ship in the same PR as the implementation. Update TECH.md in the same PR when module boundaries, implementation sequencing, risks, validation strategy, or rollout assumptions change. The checked-in spec should describe the implementation that actually ships.

For large features, the implementer may optionally keep a DECISIONS.md file summarizing concrete decisions. Offer it when it would help future agents; otherwise skip it.

Related Skills

• implement-specs

• write-product-spec

• spec-driven-implementation