| summary | One line — shown in the generated index. Written at creation; finalize at ship to state the realized result. |
|---|
One paragraph. What changes, at the level a reader needs to decide if this spec is worth reading in full.
Why now. What is broken or missing. Concrete observations / numbers, not abstract complaints. Link to memory entries or earlier specs when relevant.
What is deliberately out of scope and (when nontrivial) why. Each item is a sentence; one line each.
What changes, in enough detail that a reader who has not seen the codebase can follow. Code samples / diagrams welcome.
...
Out-of-repo steps (DNS, infra, external account changes). Omit if none.
Already covered above under Non-goals if appropriate. Repeat-list of explicitly-excluded follow-ups belongs here when the list is long.
How we know it landed correctly. New pytest? Smoke check on live URL? Lint pass? Be specific.
What could go wrong, ranked by likelihood × impact. Mitigations.