Skip to content

F22.1 — Short specs with stable work records

State Closed
Parent E22
Iteration Release 9
Closed Date 2026-11-17
Predecessors —

Stories: 2 Closed

Story State Depends on
S22.1.1 — Decide the retention boundary Closed (2026-11-16) —
S22.1.2 — Cut settled briefs and repair references Closed (2026-11-16) S22.1.1

Keep scope, decisions still to make, acceptance and links; remove implementation briefs that repeat settled code or current guides.

Context

The specs occupy 104 Markdown files and 116,546 whitespace-delimited words. The largest pages include auth design (12,000), Sonar remediation (10,292) and kiln cutover (9,025). Volume alone does not prove redundancy: active cutover acceptance and deferred entry criteria must survive.

S22.1.1 — Decide the retention boundary

State: Closed (2026-11-16)

New work keeps build detail in per-story briefs under its epic's _briefs/, deleted when the story closes, so this decision covers only pages written before that rule. Inventory each epic by state and classify prose as future design, durable decision, current usage, acceptance or historical evidence. Record a focused ADR only if the existing retention/routing rules need to change.

Acceptance:

  • Every spec page has a disposition; unfinished acceptance, dependencies, IDs and deferred entry criteria remain discoverable.
  • No current behavior moves into replacement specs; architecture and guides own it.

Decision (owner, 2026-11-16): apply the dispositions in the inventory _S22.1.1-inventory.md as proposed (keep 35, trim 42, move 21, record 2, delete none) with no new ADR; the existing retention and routing rules allow it. Before a move replaces usage prose with a link, each statement is checked against the owner page, and anything still true that it lacks is added there first. The inventory is removed when S22.1.2 closes.

Outcome: 100 pre-brief pages, 112,562 words, classified as 1,566 design, 3,514 decision, 33,798 usage, 32,138 acceptance, 35,010 evidence and 6,536 derived.

S22.1.2 — Cut settled briefs and repair references

State: Closed (2026-11-16) · Depends on: S22.1.1

Apply that disposition in small epic-sized edits. Retain closed feature records and useful acceptance; replace duplicated settled explanations with links to their current owner. Remove stale other-repository milestones from current acceptance without changing historical outcomes.

Acceptance:

  • Existing permanent IDs, links and anchors resolve or retain explicit replacement anchors.
  • Active E15, E17 and E18 acceptance and deferred epics and features retain their scope and state; no feature closes through editing prose.
  • Before/after word counts and an itemized disposition show what was removed or relocated.
  • task docs:generate is idempotent and task docs:build passes.

Outcome: the 100 pre-brief spec pages went from 112,562 to 77,404 words (−31.2%): 42 trimmed and 21 moved per the S22.1.1 inventory, 37 left as they were. Settled usage now links to its owner, and seven missing statements went into the development guide, the release runbook, the commons data guide and the Django transfer guide. No ID, state, heading anchor or acceptance changed. The inventory is deleted.

Acceptance

  • S22.1.1: Every spec page has a disposition; unfinished acceptance, dependencies, IDs and deferred entry criteria remain discoverable.
  • S22.1.2: Existing permanent IDs, links and anchors resolve or retain explicit replacement anchors.