write-tech-spec

TL;DR

The step after a product spec. Before writing, the agent reads PRODUCT.md if there is one and the code involved, and records the commit SHA of each repository it inspected, so file references link to GitHub at that commit and line range. The spec has four parts. Context: what's being built, how that area works today and the key files. Proposed changes: modules, new types, APIs and state, data flow, ownership, and the trade-offs when there's more than one reasonable path. Testing and validation: each important rule from PRODUCT.md mapped to a test or manual check. Parallelization, only when the agent has a run_agents tool: which sub-agents to run, local or remote, in which worktrees and branches, and how their work lands, or why it isn't worth it. Diagrams, an end-to-end flow, risks and follow-ups appear only when they add something. When the implementation is still too uncertain, an end-to-end prototype comes first and the spec is written from what it showed. A single-file change gets no tech spec or under 40 lines; multi-module work runs about 80 to 150. TECH.md is updated in the same PR as the implementation changes. It's written for Warp's codebase.

Summarizes the skill at 8792394.