Active decisions corpus is at its 5600-line budget — schedule the consolidation #595

Open
opened 2026-07-25 12:11:13 +02:00 by timothy · 0 comments
Owner

scripts/decisions_validate.py emits a non-blocking ::warning:: when the aggregate active corpus exceeds 5600 lines. As of PR #591 (#445/#533) it sits at 5607 — i.e. the warning is now live, where main was previously just under.

Why this is being filed rather than shaved away

I trimmed my own two records repeatedly trying to claw back the overage, and each rewrite recovered ~1 line because the content is load-bearing, not padding. Continuing would have meant deleting genuinely useful rationale from a brand-new convention record to satisfy an arbitrary cap — which degrades exactly the thing the corpus exists for. The validator's own message says "schedule a consolidation": the budget is a signal about the whole corpus, so the correct response is a consolidation pass, not per-PR starvation of whichever record happens to cross the line.

Being explicit so it isn't silently inherited: #591 is what pushed it over.

Current distribution (counted files only; migration-map.md + retrieval-eval.md are excluded by _NON_DECISION_FILES)

File Lines
docs/decisions.md ~3714
docs/decisions/workflow-process.md ~534
docs/decisions/api-auth-security.md 527
docs/decisions/optimistic-concurrency.md 318
docs/decisions/release-ci-governance.md 235
docs/decisions/README.md (generated catalog) 168
docs/decisions/spa-modularization.md 110

docs/decisions.md is ~66% of the corpus, so it's where consolidation pays.

Candidate approaches (pick after a survey, don't assume)

  1. Split by topic, as #521 already established. Several docs/decisions.md clusters are big enough to become topic files (the pattern the five existing ones follow). Pure relocation: no content lost, no lifecycle churn, and it makes decisions.md browsable again.
  2. Retire records whose subject no longer exists. Some describe code/CI arrangements later replaced; if a record's rule is no longer actionable it belongs in archive/ with status: retired, which removes it from the active count.
  3. Compress the oldest rationale prose. Older records carry long narrative that has since been absorbed into docs/*.md. Compressing to rule + signals + pointer keeps recall (which is gated on Signals:) while cutting bulk.
  4. Re-examine whether the generated catalog should count toward a budget aimed at hand-written prose.

Option 1 is likely the best value-per-risk. Note the constraint from #395/PR #566: renaming a ## HEADING fails CI as an "unlogged removal", so a consolidation must relocate headings verbatim, not retitle them.

Done-when

  • Corpus is under budget with real headroom (not landing exactly on the cap)
  • No active record lost: scripts/decisions_validate.py green, and every key: still resolves — including keys cited from docs/handoffs/, docs/superpowers/, and other docs
  • Any relocation preserves ## HEADING text verbatim (#395 constraint)
  • docs/README.md + docs/decisions/README.md reflect any new topic files
  • Adversarial review passed
`scripts/decisions_validate.py` emits a non-blocking `::warning::` when the aggregate **active** corpus exceeds 5600 lines. As of PR #591 (#445/#533) it sits at **5607** — i.e. the warning is now live, where `main` was previously just under. ## Why this is being filed rather than shaved away I trimmed my own two records repeatedly trying to claw back the overage, and each rewrite recovered ~1 line because the content is load-bearing, not padding. Continuing would have meant deleting genuinely useful rationale from a brand-new convention record to satisfy an arbitrary cap — which degrades exactly the thing the corpus exists for. The validator's own message says **"schedule a consolidation"**: the budget is a signal about the *whole* corpus, so the correct response is a consolidation pass, not per-PR starvation of whichever record happens to cross the line. Being explicit so it isn't silently inherited: **#591 is what pushed it over.** ## Current distribution (counted files only; `migration-map.md` + `retrieval-eval.md` are excluded by `_NON_DECISION_FILES`) | File | Lines | |---|---| | `docs/decisions.md` | ~3714 | | `docs/decisions/workflow-process.md` | ~534 | | `docs/decisions/api-auth-security.md` | 527 | | `docs/decisions/optimistic-concurrency.md` | 318 | | `docs/decisions/release-ci-governance.md` | 235 | | `docs/decisions/README.md` (generated catalog) | 168 | | `docs/decisions/spa-modularization.md` | 110 | `docs/decisions.md` is ~66% of the corpus, so it's where consolidation pays. ## Candidate approaches (pick after a survey, don't assume) 1. **Split by topic, as #521 already established.** Several `docs/decisions.md` clusters are big enough to become topic files (the pattern the five existing ones follow). Pure relocation: no content lost, no lifecycle churn, and it makes `decisions.md` browsable again. 2. **Retire records whose subject no longer exists.** Some describe code/CI arrangements later replaced; if a record's rule is no longer actionable it belongs in `archive/` with `status: retired`, which removes it from the active count. 3. **Compress the oldest rationale prose.** Older records carry long narrative that has since been absorbed into `docs/*.md`. Compressing to rule + signals + pointer keeps recall (which is gated on `Signals:`) while cutting bulk. 4. **Re-examine whether the generated catalog should count** toward a budget aimed at hand-written prose. Option 1 is likely the best value-per-risk. Note the constraint from #395/PR #566: renaming a `## HEADING` fails CI as an "unlogged removal", so a consolidation must **relocate headings verbatim**, not retitle them. ## Done-when - [ ] Corpus is under budget with real headroom (not landing exactly on the cap) - [ ] No active record lost: `scripts/decisions_validate.py` green, and every `key:` still resolves — including keys cited from `docs/handoffs/`, `docs/superpowers/`, and other docs - [ ] Any relocation preserves `## HEADING` text verbatim (#395 constraint) - [ ] `docs/README.md` + `docs/decisions/README.md` reflect any new topic files - [ ] Adversarial review passed
timothy added the priority: low label 2026-07-25 12:11:13 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#595