write-tech-spec
Write a
spec for a significant feature in Warp.
Overview
The tech spec should translate product intent into an implementation plan that fits the existing codebase, documents architectural choices, and makes the work easier for agents to execute and reviewers to evaluate.
Write specs to
, where
is one of:
- a Linear ticket number (e.g. )
- a GitHub issue id, prefixed with (e.g. )
- a short kebab-case feature name (e.g.
specs/vertical-tabs-hover-sidecar/TECH.md
Match the id used by the sibling
when one exists.
should contain only id-named directories as direct children.
Ticket / issue references are optional. If the user has a Linear ticket or GitHub issue, use its id. If they don't, ask them for a feature name to use as the directory. Only create a new Linear ticket or GitHub issue when the user explicitly asks for one; in that case use the Linear MCP tools or
CLI respectively (and
if team, labels, or repo are unclear).
When to use
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
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
app/src/workspace/workspace.rs (120-220)
-
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
directly rather than restating them; each important invariant should map to a concrete test or verification step. This section is where validation lives —
intentionally does not have a Validation section.
-
Parallelization — Actively evaluate whether parallel sub-agents (launched via
) would meaningfully reduce wall-clock time or isolate work. Skip this section if
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 ( or ) 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 (
or
) 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 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
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
file summarizing concrete decisions. Offer it when it would help future agents; otherwise skip it.
Related Skills
spec-driven-implementation