spec-forgelisted

# Spec forge The spec is where the human spends their judgement, so the implementation does not have to interrupt them for it. Every question this document leaves open becomes a mid-run question or a wrong guess. Write it to be **executable**: a competent agent should be able to run it end to end without a conversation. ## 1 — Gather the ground truth Before writing anything, collect what the spec must be consistent with: - **The ask** — ticket text, or the user's paragraph. Quote it verbatim in the spec; paraphrase drifts. - **The map** — `docs/agent/repo-map.md` for which projects the change touches and what their stacks are. - **The vocabulary** — `docs/agent/glossary.md` for what the business terms mean in code. - **The contract** — `api-contract-sync` for the real shape of every endpoint involved. A spec that assumes a field the API does not serve fails at implementation time, when it is expensive. - **The precedent** — `pattern-mine` on the nearest comparable feature. The spec should say "like X, but Y", because that is both shorter and more precise than describing the target from scratch. ## 2 — Write the acceptance criteria Criteria are **observable**, in Given/When/Then, phrased so a test could assert them and a human could check them in a browser. "The list loads quickly" is not a criterion; "the list renders within 2s on a 3G profile with 500 rows" is. Cover the full state matrix, because the happy path is the part nobody forgets: - **Empty** — no data yet,