-
Notifications
You must be signed in to change notification settings - Fork 18
Description
Problem
The docs/design-plans/ directory contains ~3,000 lines across 10 implementation plan documents. Many of these include verbatim code snippets (struct definitions, function signatures, step-by-step implementation sequences) that served as working plans during development. Once the corresponding feature lands, these code snippets drift from the actual implementation and become misleading.
For example, the systems-format plan (2026-03-18-systems-format.md) includes ~1,800 lines with inline code blocks showing proposed struct layouts and function bodies. After the PR merges and the code evolves, these snapshots become stale.
Why it matters
- Correctness: Developers or agents reading design-plans may mistake stale code snippets for accurate documentation of how the code actually works.
- Maintainability: Keeping implementation-level details in sync across both the code and separate plan documents is unsustainable.
- Signal-to-noise: The high-level design rationale, constraints, and test requirements in these documents are valuable. The verbatim code is not -- it duplicates what is already in the source.
Components affected
docs/design-plans/(all 10 files, ~3,000 lines total)
Suggested approach
For each completed plan:
- Keep: design rationale, constraints, acceptance criteria, test requirements, architecture decisions.
- Remove or summarize: verbatim code snippets, step-by-step implementation sequences, proposed struct/function bodies.
- Optionally add a note at the top indicating the plan has been implemented, with a link to the relevant PR or commit range.
For plans corresponding to features still in progress, defer cleanup until the feature lands.
Context
Identified during review of PR #398 (systems format support).