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:
- 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.
- 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.
- 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?
Problem
_plans/holds 56 plans, 16.7k lines. Each is written once, at the moment an implementation starts, and deliberately never revised:_plans/README.mdsays 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/NNNin 23 files, including code comments,docs/root-model.md,docs/confluence/api.mdand CLAUDE.md. 28 commit messages cite plans too.Possible solution
Keep plans, but out of the repository, attached to the discussion they came from:
markfluence CMD --help,docs/, and CLAUDE.md. Reasoning the code depends on belongs in a code comment or indocs/, not in a plan.Migrating the existing plans:
_plans/NNNcitation 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 ordocs/first._plans/, and update the workflow notes in CLAUDE.md and the README's link.Commit messages that cite
_plans/NNNkeep working:git show <commit>:_plans/NNN_…still finds the file at that commit.Open questions