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

Solution, from user's perspective.

## User Stories

LONG numbered list: "As an <actor>, I want <feature>, so that <benefit>".
Example: "As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending."
Extremely extensive — cover all aspects.

## Implementation Decisions

Decisions made: modules built/modified, interfaces, technical clarifications, architecture, schema changes, API contracts, specific interactions.

Hard-to-reverse or surprising decisions → also record as ADR (`writing-adrs`) + reference. Decision only in conversation, not listed here → fails litmus test — write it down.

No file paths/code snippets — stale fast. Exception: prototype snippet encoding a decision more precisely than prose (state machine, reducer, schema, type shape) → inline within relevant decision, note prototype origin, trim to decision-rich parts.

## Testing Decisions

What makes a good test (external behavior only, not implementation details), which modules tested, prior art in codebase.

## Out of Scope

What this spec excludes.

## Further Notes

Anything else.