菜单
Write a TECH.md spec for a significant Warp feature after researching the current codebase and implementation constraints. Use when the user asks for a technical spec, implementation plan, or architecture doc tied to a product spec.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | write-tech-spec |
| description | Write a TECH.md spec for a significant Warp feature after researching the current codebase and implementation constraints. Use when the user asks for a technical spec, implementation plan, or architecture doc tied to a product spec. |
Write a TECH.md spec for a significant feature in Warp.
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:
specs/APP-1234/TECH.md)gh- (e.g. specs/gh-4567/TECH.md)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).
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.
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.
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 @ <commit-sha> — entry point for the user flowapp/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.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:
local or remote) with a one-line rationale.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.
Right-size the spec to the feature:
If Context and Proposed changes end up describing the same files and state from different angles, collapse them.
PRODUCT.md for behavior instead of restating it.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.
implement-specswrite-product-specspec-driven-implementationProduce a polished, self-contained HTML "readout" document under ~/.readouts (with an auto-maintained index page), either by snapshotting the findings accumulated in the current conversation or — when invoked fresh, e.g. "/readout on how github webhook events are processed" — by sharpening scope with clarifying questions and researching the codebase before documenting. The work runs in a child agent so the main conversation's context stays clean. Use whenever the user invokes /readout, says "write this up", "turn this into a doc/page", "make a readout", or asks for a readable, shareable document capturing findings or explaining how something works.
Scan warpdotdev/warp and warp-server for recently merged PRODUCT.md specs that don't yet have a corresponding docs PR in warpdotdev/docs. When a complete spec is found, auto-generates a full docs draft PR and tags the engineer. When a spec is too thin to draft from, pings the engineer directly. Designed to run as a scheduled Oz ambient agent (e.g., every 2-3 days). Use when setting up the automated docs trigger or running a manual docs coverage sweep.
Draft a complete documentation page for a new Warp feature from its PRODUCT.md and/or TECH.md spec. Use when an engineer has written a spec and needs to produce a first-pass MDX draft for the warpdotdev/docs repo. Also handles features without specs by researching the codebase first. Invoke this skill whenever an engineer mentions writing docs for a feature, drafting a docs page, creating feature documentation, starting the eng-docs workflow, or converting a spec into documentation. Works from warp-internal or warp-server.
Run an autonomous, spec-driven development "saga" for medium-to-large features using an orchestrator agent and a fleet of worker subagents. Use this skill whenever the user invokes /saga, asks to autonomously build a sizable feature end-to-end with minimal human intervention, wants a comprehensive spec broken into milestones and tasks with airtight validation criteria before parallelized implementation, or wants an orchestrator to delegate implementation to worker agents while preserving its own context window. Trigger on phrases like "run a saga", "autonomously implement this feature", "spec it out then build it with subagents", "orchestrate this big feature end-to-end", or "build this with workers and validate each step". Also use this skill when asked to continue, resume, or pick up an existing saga from its saga directory (e.g. under ~/.sagas).
Run a second round on a contested question by circulating each subagent's independent proposal to the other authors and asking for structured pros and cons, then synthesize. Use this skill whenever you have multiple independent proposals or opinions on a contested decision — architecture tradeoffs, code review disagreements, design choices, competing root-cause theories — and want sharper analysis than you'd produce by synthesizing alone. Pairs naturally with the council and research skills; reach for it liberally whenever proposals diverge.
Delegate noisy investigation to one or more subagents so the orchestrator's context stays clean, then work from the distilled answer. Use this skill whenever answering a question would require reading many files, long logs, large diffs, or wide codebase surveys — i.e. when producing the answer generates far more noise than the answer itself. Use it for "how does X work", "where is Y used", "what's the root cause of Z", "summarize this PR/log" style questions, and reach for it liberally before reading a pile of files inline.