to-spec

To Spec

Produce spec (aka PRD) from current conversation + codebase understanding. Do NOT interview user — synthesize what you already know.

Reproducibility invariant

Spec — and tickets later derived from it — must be self-contained: replayed by any implementer, human or agent, builds roughly same application. Every outcome-shaping decision lives in spec itself, or durable docs it references — ADRs (writing-adrs), glossary terms (docs/glossary/). Never conversation context, tribal knowledge, implementer discretion.

Litmus test: two independent implementers could build meaningfully different things → spec underspecified. Add decision to spec, or record as ADR/glossary term + reference.

Grilling gate

Spec is load-bearing. No grilling session (docs/glossary/grilling-session.md) in context → stop, ask user: "No grilling session found — really skip?" Proceed only on explicit confirmation; note skip in Further Notes.

Process

1. Explore repo if not already done. Use glossary vocabulary (uvx disambiguate <term>) throughout; respect ADRs in touched area.

2. Sketch seams for testing the feature. Prefer existing seams; new seams at highest point possible. Fewer seams better — ideal is one.

   Check seams with user.

3. Write spec per template — as short as possible, caveman mode preferred (caveman skill), precision and understandability must not suffer. Apply litmus test to every section, publish per consumer repo's tracker conventions (AGENTS.md). Apply ready-for-agent label — no further triage.

Spec template:

## Problem Statement
 
Problem, from user's perspective.
 
## Solution