You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Severity MED. Filed against the doctrine's own standard, which is what makes it worth filing.
The measurement
$ wc -l docs/agentic-dev-kit/*.md docs/agentic-dev-kit/workflows/*.md
598 fallback-review-panel.md <- must be read in full before every panel
354 workflows/pr-watch.md
342 workflows/parallel.md
183 workflows/session-start.md
155 workflows/wrap-up.md
155 adopting-into-a-linted-repo.md
131 workflows/parallel-headless.md
55 safety-critical-changes.md <- the doctrine this one serves
fallback-review-panel.md is 598 lines — 69% longer than the next-largest doc, and 10.9× the safety doctrine it exists to implement.pr-watch.md instructs reading it before running the panel, and its content is genuinely load-bearing, so it is read in full each time.
Why this is a defect and not a preference
The file's own "Keep the record small" section states: "A record's defect surface is proportional to its length, and every correction round adds to it." It then documents three separate attempts to bound record length, each of which opened a hole, and prescribes deleting over amending.
Applied to itself, that argument lands. The file has grown by accretion from exactly the process it describes — each panel round that found something added a paragraph explaining what and why — and it now carries:
Three buried designs described at length specifically so nobody re-proposes them (the "Three attempts to bound that" list). Valuable history; not instructions.
A ~180-line stopping section mixing the executable rule (which pass type, when) with the evidence for it and the reasoning against alternatives.
Rationale interleaved with instruction throughout, so an agent cannot skim to the obligations without risking dropping one.
The concrete cost
Ten panel rounds this session (PRs #202, #207). Each began by reading all 598 lines to author two launch prompts. The prompts were hand-written each time, so the contract items reached each lens through my re-reading rather than through any mechanism — and an item omitted by fatigue would be invisible.
Suggested
Split by what executes versus what explains, which is the discriminator this file already applies to everyone else's prose:
The contract and the procedure — the numbered items, the pass-type rules, the receipt commands. Short enough to read before every panel without skimming.
The evidence and the buried designs — the measurements, the three failed bounds, the per-round histories. Moved to a companion, linked once. Nothing executes it; it exists so a future proposal is not re-litigated.
Both stay kit-owned and manifest-tracked, so /upgrade ships both and neither can dangle (which is #37/#146's hazard, now guarded by the link tests added in #207).
Worth doing alongside #167, since splitting the file is the occasion to renumber the contract, and renumbering is the thing that issue says is currently blocked.
The counter-argument, stated because it is strong
Much of the length is load-bearing: the buried designs exist because each was proposed and adopted before being found holed, and a shorter file would invite re-proposing them. Deleting history here is how the holes reopen. So this is explicitly not an ask to cut content — it is an ask to separate the part that must be executed correctly under fatigue from the part that must merely be findable.
Related
#167 (contract item 7 carries four requirements; renumbering blocked), #120 (a cheaper terminal check for record accuracy — the same "length has a cost" argument aimed at PR prose rather than doctrine), #209 (proportionality — a shorter contract is what would make a cheaper pass safely specifiable).
Severity MED. Filed against the doctrine's own standard, which is what makes it worth filing.
The measurement
fallback-review-panel.mdis 598 lines — 69% longer than the next-largest doc, and 10.9× the safety doctrine it exists to implement.pr-watch.mdinstructs reading it before running the panel, and its content is genuinely load-bearing, so it is read in full each time.Why this is a defect and not a preference
The file's own "Keep the record small" section states: "A record's defect surface is proportional to its length, and every correction round adds to it." It then documents three separate attempts to bound record length, each of which opened a hole, and prescribes deleting over amending.
Applied to itself, that argument lands. The file has grown by accretion from exactly the process it describes — each panel round that found something added a paragraph explaining what and why — and it now carries:
The concrete cost
Ten panel rounds this session (PRs #202, #207). Each began by reading all 598 lines to author two launch prompts. The prompts were hand-written each time, so the contract items reached each lens through my re-reading rather than through any mechanism — and an item omitted by fatigue would be invisible.
Suggested
Split by what executes versus what explains, which is the discriminator this file already applies to everyone else's prose:
Both stay kit-owned and manifest-tracked, so
/upgradeships both and neither can dangle (which is #37/#146's hazard, now guarded by the link tests added in #207).Worth doing alongside #167, since splitting the file is the occasion to renumber the contract, and renumbering is the thing that issue says is currently blocked.
The counter-argument, stated because it is strong
Much of the length is load-bearing: the buried designs exist because each was proposed and adopted before being found holed, and a shorter file would invite re-proposing them. Deleting history here is how the holes reopen. So this is explicitly not an ask to cut content — it is an ask to separate the part that must be executed correctly under fatigue from the part that must merely be findable.
Related
#167 (contract item 7 carries four requirements; renumbering blocked), #120 (a cheaper terminal check for record accuracy — the same "length has a cost" argument aimed at PR prose rather than doctrine), #209 (proportionality — a shorter contract is what would make a cheaper pass safely specifiable).