Skip to content

Prune ephemeral implementation plans from docs/design-plans/ #407

@bpowers

Description

@bpowers

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:

  1. Keep: design rationale, constraints, acceptance criteria, test requirements, architecture decisions.
  2. Remove or summarize: verbatim code snippets, step-by-step implementation sequences, proposed struct/function bodies.
  3. 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).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions