Write Tech Spec

write-tech-spec

Write a TECH.md 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 specs/<id>/TECH.md, where <id> is one of:

• a Linear ticket number (e.g. specs/APP-1234/TECH.md)
• a GitHub issue id, prefixed with gh- (e.g. specs/gh-4567/TECH.md)
• a short kebab-case feature name (e.g. specs/vertical-tabs-hover-sidecar/TECH.md)

Match the id used by the sibling PRODUCT.md when one exists. specs/ 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 gh CLI respectively (and ask_user_question 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 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. When referencing relevant code chunks in the spec, prefer commit-pinned references so future readers can inspect the exact code you researched. Capture the current commit SHA for each repository you inspected (for example, git rev-parse HEAD) and, when possible, make file references Markdown links to the corresponding GitHub blob/<sha>/...#Lx-Ly URL. Use the linked text to keep the path readable in the spec.

Structure

Required sections:

1. 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 @ <commit-sha> — entry point for the user flow
   • app/src/workspace/workspace.rs (120-220) @ <commit-sha> — state and event handling that will likely change Reference PRODUCT.md for user-visible behavior rather than restating it.

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

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

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