Tech Spec

Tech Spec

A tech spec is a typed call-stack architecture handoff: code-shaped contracts plus execution flows. Prefer TypeScript pseudocode over prose wherever precision matters.

This skill is design-only. Do not implement. Save a file only when the user asks for a file; otherwise return the spec inline.

Branch selection

1. Use Path A: Convert context to spec when the conversation, docs, or codebase already contain enough background to describe the change.
2. Use Path B: Grill first when the user wants a new spec but has not provided enough problem, constraints, design direction, affected code, or acceptance criteria.

If a question can be answered by exploring the codebase, inspect the codebase instead of asking.

Completion criterion: the branch is chosen from actual available context; missing architectural decisions are not invented.

Path A: Convert context to spec

1. Load standards and local context

Inspect existing code and docs for local vocabulary, module layout, domain concepts, errors, adapters, observability, runtime patterns, and test style.

Completion criterion: the spec uses project vocabulary and does not introduce a pattern, library, adapter, schema style, or test strategy before checking local precedent.

2. Extract the design problem

Capture:

• current state;
• problem;
• users/callers;
• goals;
• non-goals;
• constraints;
• invariants;
• affected systems;
• likely entrypoints;
• operational/runtime concerns;
• risks;
• open questions.

Mark unknowns as open questions instead of filling gaps with plausible design.

Completion criterion: every claimed requirement or constraint is grounded in conversation, code, docs, or an explicit open question.

3. Explore design alternatives

Produce materially different alternatives before choosing the recommended design. Alternatives should differ in interface shape, seam placement, ownership, call stack, runtime topology, or module boundaries — not just names.

For each alternative, sketch:

• domain types and state model;
• public/module interfaces and APIs;
• input/output types;
• expected failure types;
• seams, boundaries, and adapters;
• entrypoint-to-side-effect call stack;
• parsing/projection strategy;
• authorization, observability, cancellation, idempotency, and transaction flow when reachable;
• test seam strategy;
• tradeoffs.

Compare alternatives on:

• caller burden;
• module depth and leverage;
• locality of invariants and change;
• seam placement;
• boundary parsing and projections;
• error and cancellation model;
• testability through real seams;
• operational/runtime fit;
• implementation complexity.

Completion criterion: the recommendation is chosen after comparing alternatives, not before.

4. Specify the recommended typed contracts

For the recommended design, outline every new, changed, or deleted:

• domain value;
• branded/refined type;
• state machine variant;
• input/output type;
• request/response shape;
• function signature;
• class or module interface;
• expected-failure/custom-error type;
• adapter interface;
• protocol DTO;
• persistence DTO/projection;
• runtime-boundary codec;
• public API.

Name seams, adapters, implementations, ownership boundaries, and what crosses each boundary. State what each layer may know and what must not leak across the seam.

Completion criterion: every new or changed boundary has a concrete type/interface/API sketch, or an explicit reason no new contract is needed.

5. Specify call stacks and data flow

For every new, changed, or deleted behavior, show the call stack from entrypoint to side effects and response.

Include type/data flow:

raw input
  -> boundary DTO / unknown
  -> parser
  -> canonical domain/application input
  -> service/module interface
  -> adapter call
  -> typed result/error
  -> projection
  -> serialized output

Include current vs proposed flow when changing existing behavior. Include failure, retry, cancellation, transactionality, idempotency, observability, authorization, and runtime-hop flow when reachable.

Completion criterion: every affected behavior has an end-to-end call stack and type/data-flow trace.

6. Map files and modules

List:

• files/modules to add;
• files/modules to change;
• files/modules to delete, if any;
• test files;
• config/migration/runtime files, if any.

For each file, state the contract, code path, boundary, adapter, domain concept, or test responsibility it owns.

Completion criterion: every contract and call-stack step maps to a file/module or an open question.