write-tech-spec

Translate approved product intent into an implementation plan that fits the existing codebase. This is a local shared skill; wrappers may provide exact inputs and output paths that take precedence.

Decide and research

Use it when work spans modules, has architectural tradeoffs, needs a migration or rollout plan, or benefits from review before implementation. Skip it for straightforward fixes, small refactors, and narrow UI changes with no technical ambiguity. Prefer a product spec first; an end-to-end prototype can be a better precedent when the implementation is still uncertain.

Before drafting, read the product spec when present and inspect the actual repository. Identify current behavior, relevant files/types/entry points, data or control flow, ownership boundaries, dependencies, risks, and validation constraints. Do not infer architecture that can be read from code.

When a code reference matters, pin it to the inspected commit SHA and include a repo-relative path with line numbers. Add a GitHub blob/<sha>/...#Lx-Ly link when the repository has an accessible remote; otherwise keep the local reference. Reference the product spec for behavior rather than restating it.

Write the spec

Use the following core sections, keeping each only as detailed as the decision requires:

1. Problem — the technical problem and its product relationship.
2. Relevant code — files, symbols, entry points, and current ownership.
3. Current state — how the system works and limitations that matter.
4. Proposed changes — affected modules, types/APIs/state, data flow, ownership boundaries, sequencing, and tradeoffs.
5. Testing and validation — map tests, manual checks, screenshots/videos, or other evidence to the product behavior and its numbered invariants.

Add these sections when they add signal:

• End-to-end flow — when tracing the main path clarifies the change list.
• Risks and mitigations — when there are real regression, migration, rollout, or compatibility hazards.
• Follow-ups — when there is deferred technical debt or an open technical question.

For small changes, combine the problem, current state, and relevant code into a short context section when the wrapper permits it. Omit empty optional sections; do not pad the document with generic architecture prose. Evaluate parallel work only when the surrounding workflow explicitly allows delegation and it materially reduces time or isolates ownership; otherwise omit it.

Right-size and maintain

A single-file change may not need a tech spec; a multi-module feature is often about 80–150 lines; larger documents are justified by real cross-cutting risk. If implementation diverges from the plan, update tech.md in the same change when practical. An optional DECISIONS.md can capture major technical choices for large features, but is not required.

Related skills: write-product-spec, spec-driven-implementation, and implement-specs.