Skip to content

Move plans out of the repository so a stale plan cannot be mistaken for how markfluence works #209

Description

@willkg

Problem

_plans/ holds 56 plans, 16.7k lines. Each is written once, at the moment an implementation starts, and deliberately never revised: _plans/README.md says a plan "describes what was intended at the moment it was written" and is "not documentation". But decisions get rethought after a plan lands, and the plan keeps saying the old thing.

That warning lives in one README that nobody passes through. Someone who greps for a function, a field or a flag lands directly on a plan, which is the most detailed and confident text in the repository about that thing, and can come away with the wrong understanding of how it is implemented. Two recent examples of plans drifting:

  • _plans/053 (update moves pages) planned a loop check through v2's ancestors route; the implementation found that route needs a scope nothing else uses and walks parent links instead.
  • _plans/055 (raw tables) was amended five times during implementation, including a measured correction of how a cell's alignment works.

Both record their amendments, but only at the end, after the original decisions a reader meets first. Claude Code reads the repository the same way a person does, and treats a plan as authoritative.

The repository also sends readers there on purpose: 38 citations of _plans/NNN in 23 files, including code comments, docs/root-model.md, docs/confluence/api.md and CLAUDE.md. 28 commit messages cite plans too.

Possible solution

Keep plans, but out of the repository, attached to the discussion they came from:

  • A plan is a comment on the issue it answers, posted before implementation starts. It is dated and sits beside the discussion that produced it, so it reads as history, because an issue is history. Work without an issue gets one first.
  • Amendments go in the PR description ("amended during implementation"), where review already happens, rather than into an edited plan.
  • Current behaviour stays where it is: markfluence CMD --help, docs/, and CLAUDE.md. Reasoning the code depends on belongs in a code comment or in docs/, not in a plan.

Migrating the existing plans:

  1. 37 of the 55 plans name the issue they answer. Post a comment on each of those issues linking to the plan at the last commit that has it (a permalink, rather than pasting 16k lines into issues; every plan would fit in a comment if pasting turns out to be better). The other 18 remain in git history.
  2. Replace each _plans/NNN citation in code, docs and CLAUDE.md with the issue number. Where a comment leans on the plan for reasoning it does not state itself, move that reasoning into the comment or docs/ first.
  3. Delete _plans/, and update the workflow notes in CLAUDE.md and the README's link.

Commit messages that cite _plans/NNN keep working: git show <commit>:_plans/NNN_… still finds the file at that commit.

Open questions

  • Permalink or pasted text for the existing plans?
  • Is an issue comment the right home, or would the PR description, a GitHub Discussion, or the wiki serve better?

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions