Tech Spec Writer

---
name: tech-spec-writer
description: 'Write a TECHNICAL SPEC / design doc for a non-trivial engineering effort — broader than an ADR: problem/context, goals and non-goals, the proposed technical design (architecture, data model, APIs, components and how they interact), alternatives considered, cross-cutting concerns (security, privacy, performance, observability, migration/rollout, testing), risks and open questions, and a review/sign-off path. A tech spec covers the WHOLE design of a change (often several decisions); an ADR records ONE decision; a PRODUCT spec is the user-facing what/why. Composes adr-writer for embedded decisions and architecture-designer for structure. Use when writing a design doc/RFC for a substantial change, or when an effort needs design review before build. Do NOT use to record ONE decision (adr-writer), write the user-facing product spec (product-spec-writer), produce the system structure itself (architecture-designer), or run the design review (design-review-facilitator).'
---

# Tech Spec Writer

**Reading key:** ADR means architecture decision record, RFC means request
for comments, API means application programming interface, and PII means
personally identifiable information.

## Purpose

A substantial change built without a technical spec is a change whose
design lives in one person's head and surfaces, contradicted, at code
review. The tech spec is where the design gets written down and agreed
BEFORE the build: the problem and why now, the proposed technical
approach with its data model and interfaces, the alternatives weighed,
the cross-cutting concerns teams forget until production (security,
privacy, performance, observability, migration, testing), the risks, and
the sign-off path. This skill writes that document — broader than an ADR
(which records one decision) and different from a product spec (which is
the user-facing what/why). It composes `adr-writer` for the individual
binding decisions inside it and `architecture-designer` for the structural
work; it presents and integrates them into a reviewable design.

## Use When

- Use when: writing a technical design doc / RFC / design proposal for a
  non-trivial change before implementation.
- Use when: an effort needs design review and sign-off across engineers
  before build starts.
- Use when: a change spans multiple components/decisions and needs a
  single coherent design others can review.
- Use when: cross-cutting concerns (migration, rollout, observability,
  testing) must be designed up front, not discovered late.
- Do NOT use when: the artifact is ONE architecture decision with its
  alternatives and consequences — that is `adr-writer` (a tech spec may
  embed/cite several ADRs).
- Do NOT use when: the artifact is the user-facing PRODUCT spec (problem,
  scope, user stories, acceptance) — that is `product-spec-writer`.
- Do NOT use when: the task is DECIDING the system structure itself
  (component/dependency map, tradeoffs) — that is `architecture-designer`;
  the tech spec presents and consumes that, it doesn't re-derive it.
- Do NOT use when: running the design review itself (reviewers, discussion,
  explicit outcome) — that is `design-review-facilitator`; this skill writes
  the design doc that review examines.

## Inputs to Inspect

1. The change and its driver: the problem, the product requirement or
   incident behind it, and why now — the spec's opening.
2. The current system: the components, data, and interfaces the change
   touches, inspected (not imagined), so the design is grounded.
3. Existing decisions and structure: relevant ADRs (`adr-sequencer` corpus)
   and any `architecture-designer` output the spec must respect or extend.
4. The requirements: the product spec (`product-spec-writer`) or
   requirements brief the technical design must satisfy.
5. The reviewers and bar: who signs off, and the concerns they'll raise
   (security, data, ops) so the spec addresses them proactively.

## Workflow

1. **Frame problem, goals, non-goals.** Open with the problem and why
   now, the goals (what the design must achieve), and explicit non-goals
   (scope boundary). A spec without non-goals invites scope creep in
   review.
2. **Present the proposed design.** The technical approach: the
   architecture/structure (from `architecture-designer` where it changes),
   the data model, the APIs/interfaces, the key components and how they
   interact — concrete enough to build from, with diagrams where they
   help.
3. **Show the alternatives.** The main options considered and why the
   proposal wins — the reasoning reviewers need. Individual binding
   decisions get recorded as ADRs (`adr-writer`) and cited, not re-argued
   inline.
4. **Design the cross-cutting concerns.** Security and privacy
   (authorization, data handling, PII), performance (budgets, hot paths),
   observability (what's logged/metered), migration and rollout
   (staged? reversible?), and testing strategy. These are where specs
   earn their keep — the concerns that bite in production if unplanned.
5. **State risks and open questions.** The real risks with mitigations,
   and the open questions blocking or needing a decision — named, with
   owners, not buried. Before asking an owner to choose during the build,
   check whether the evidence can support a recommendation. If a deciding
   fact is missing (one without which the evidence cannot favor any option),
   ask only for that fact this turn. Otherwise, explain unfamiliar terms in
   plain language and show the viable options supported by the evidence.
   For each, give the reason to consider it, benefits, drawbacks, and money,
   setup, and upkeep costs (or mark an unknown). Recommend one with a
   case-specific reason and say what would change that recommendation,
   naming any unverified figure that could shift it. Then ask exactly one
   atomic owner question;
   the answer sets the design only and does not authorize starting the
   build. Do not invent options or present an
   unresolved assumption as a fact. Record a binding technical choice in
   an ADR (`adr-writer`) and cite it here.
6. **Define the review/sign-off path.** Who reviews, what approval means,
   and how the spec becomes the agreed design. A spec nobody signs is a
   suggestion.
7. **Compose, don't duplicate.** Cite ADRs for decisions,
   `architecture-designer` for structure, the product spec for the what/
   why. The tech spec integrates them into one reviewable design; it
   doesn't re-author them.
8. **Deliver** the spec in the Output Format, with known/assumed/open
   separated and cross-cutting concerns explicitly addressed.

The tech-spec template, the cross-cutting-concerns checklist, and the
spec-vs-ADR-vs-product-spec discriminator:
[references/tech-spec-sheet.md](references/tech-spec-sheet.md).

## Output Format

```
TECH SPEC — <effort>
Problem & why now: <context, driver>
Goals / Non-goals: <what the design achieves / explicit out-of-scope>
Proposed design:   architecture (→ architecture-designer if structural), data model, APIs,
                   components + interactions (diagrams where useful)
Alternatives:      <options + why the proposal wins>  (decisions → ADRs, cited)
Cross-cutting:     security/privacy · performance · observability · migration/rollout · testing
Risks & open Qs:   <risks + mitigations; open questions with owners>
Review/sign-off:   <reviewers; what approval means>
Known / assumed / open separated
Boundaries:        one decision → adr-writer; user-facing → product-spec-writer;
                   structure → architecture-designer
```

## Validation Checklist

- [ ] Problem, goals, and explicit non-goals open the spec.
- [ ] The proposed design is concrete (data model, APIs, components/
      interactions) and grounded in the current system.
- [ ] Alternatives are shown with why the proposal wins; binding decisions
      are cited as ADRs, not re-argued.
- [ ] All cross-cutting concerns are addressed: security/privacy,
      performance, observability, migration/rollout, testing.
- [ ] Risks have mitigations; open questions have owners. Owner-facing
      choices explain terms, viable options, reasons, pros/cons, costs or
      unknowns, and a reasoned recommendation before asking.
- [ ] A review/sign-off path is defined.
- [ ] Structure, single-decision, and product-spec content are composed
      from their owning skills, not duplicated.
- [ ] Known/assumed/open are separated; the spec isn't confident fiction
      over unresolved design.

## Gotchas

- A tech spec with no non-goals expands in review until it's a re-
  architecture; the boundary is half the document's value.
- The concerns that sink projects — migration, rollout, observability,
  data privacy — are exactly the ones specs skip because they're not the
  "fun" design. Design them up front or debug them in production.
- Re-arguing a decision inline that belongs in an ADR bloats the spec and
  loses the record; cite the ADR (`adr-writer`) and move on.
- A design doc that presents only the chosen approach, with no
  alternatives, gives reviewers nothing to push on and hides the
  reasoning. Show the roads not taken.
- A spec nobody is required to sign off is a suggestion that gets ignored
  the first time it's inconvenient. Name the reviewers and what approval
  means.
- Writing the technical design over an unclear product requirement builds
  the right thing wrong; if the what/why is fuzzy, that's
  `product-spec-writer`/`requirements-gathering-facilitator` first.
- A tech spec is not the architecture decision. If you're deriving the
  component/dependency structure from scratch, that's
  `architecture-designer`; the spec presents its result.

## Stop Conditions

- The artifact is ONE architecture decision (context/decision/
  alternatives/consequences/rollback) → route to `adr-writer`.
- The artifact is the user-facing product spec → route to
  `product-spec-writer`.
- The task is deciding the system STRUCTURE itself → route to
  `architecture-designer`; the spec consumes that output.
- The product requirement the design must satisfy is unclear or contested
  → route to `product-spec-writer` / `requirements-gathering-facilitator`
  before designing; a technical spec can't rescue an undefined goal.

## Supporting Files

- [references/tech-spec-sheet.md](references/tech-spec-sheet.md) — the
  tech-spec template, the cross-cutting-concerns checklist, and the
  spec-vs-ADR-vs-product-spec discriminator.
- `evals/evals.json` — behavior cases including the cross-cutting design,
  the cite-don't-re-argue-ADR discipline, and the fuzzy-requirement
  refusal.
- `evals/trigger-evals.json` — discrimination against `adr-writer` (one
  decision), `product-spec-writer` (user-facing), and `architecture-designer`
  (structure).