Retiring finished plans¶
A plan in docs/plans/ is written to get one piece of work done.
Once that work is finished, the plan is retired: what it knew that
is still worth knowing is moved to where it will be maintained, and
its files are deleted. This page defines when a plan is eligible and
what retiring one involves.
Why¶
Nothing removes a finished plan, so docs/plans/ only grows. In
October 2026 shakenfist and ryll each held over 180 plan files --
more than 100,000 lines in shakenfist -- and ryll had 23 plans that
had been finished for more than 90 days. Every agent session that
searches a repository wades through plans describing code that has
since been rewritten, and treats them as current. Worse, what a
finished plan holds that the documentation does not -- why the code
is that shape, which designs were tried and rejected, the work it
deferred -- is never read again, so it is lost while still sitting
in the tree.
Eligibility¶
A plan is eligible for retirement when both of these hold:
- its row in
docs/plans/index.mdhas the statusComplete,SupersededorAbandoned; and - that status was reached more than 90 days ago: the clock starts at the commit where the row last changed into a terminal status.
The clock is the status change, read from the history of
docs/plans/index.md, rather than the last commit touching the
plan or a date written into it. Finished plans are edited all the
time by changes that are not about them -- a sweep making links
absolute, a template fix, and retirement itself rewriting pointers
in other plans -- so a clock that restarts on every touch never runs
out. A plan that is reopened and finished again starts a new clock.
Only a change into a terminal status from one that is not starts
the clock: a move from one terminal status to another, such as
Complete to Superseded, and an edit that leaves the status
alone, such as rewriting the row's link, do not.
Superseded and Abandoned plans retire on the same clock; for an
abandoned plan, the reasoning worth keeping is usually why it was
abandoned.
A plan listed in a table with no Status column records no status,
so it is never eligible. The audit reports such plans and never
fails for them, because the alternative is demanding a status that
somebody invents to clear an issue, and an invented status in the
one page people read to decide what wants attention is worse than
none. A repository that keeps such a table should say in its index
why, as private-ci does.
What retiring involves¶
docs/describes what the plan built. Usually it already does; where it does not, the gap is filled.- The plan's reasoning is written down where it will be
maintained -- in
docs/, or inARCHITECTURE.mdwhere it is about the shape of the system. That means the constraints it verified, the measurements it took, the alternatives it rejected and why, and any push-audit findings it declined in writing. This is the part most easily lost, and the part whose loss costs most: it is how the next change avoids re-proposing a design that has already failed. - Each Future work item still worth doing becomes a GitHub
issue, labelled
from-retired-plan. The issues are filed while the pull request is prepared and listed in its body; if the pull request is closed unmerged, they are closed again. Items dropped instead are listed in the body too, each with a reason. - Every pointer to the plan is rewritten, to the new home of
whatever it was pointing at, or to the permalink below. Search for
each file's basename (
git grep -n PLAN-example.md), master and phase files alike. Two kinds of pointer are caught if missed: relative links insidedocs/are reported bydocs-external-links, and plan references in source byplan-source-references. Nothing catches the rest, which become silent 404s and stale names: absoluteblob/<branch>links inREADME.md, and plan names in backticks inAGENTS.md,ARCHITECTURE.md, other plans and.claude/. A build input underdocs/plans/, such asorder.yml, is the exception: it is keyed by file name, and the file is going away, so its entry is deleted rather than pinned to a permalink. - The master plan and its phase files are deleted.
- The index row stays. It keeps its date, intent and status, and its link becomes a permalink to the plan's final text:
where <sha> is
That is the last commit on the default branch that changed the
file, so it holds the final text and, being on the default branch,
is never garbage collected. Never link blob/main: once the file
is deleted that is a 404. The index stays the complete history of
what the repository has planned, and git keeps the text. The row
is marked (retired) after its link, in the Plan cell, and the
index says once, in a paragraph before its table, what a pinned
link means. That paragraph says the pinned copy is frozen history
rather than a maintained document, so it may state things a later
phase overturned. A row whose link is an absolute URL registers no
local plan, so plan-index accepts a
retired row as it stands.
What it is not¶
- Retired is not a status. A retired plan's row still reads
Complete,SupersededorAbandoned. A status says whether a plan still wants attention, and a retired plan does not; that its text now lives only in history is already shown by the link. The(retired)marker does not contradict this: it sits in thePlancell, beside the link, and theStatuscell is untouched. It labels the link, saying that the text behind it is frozen, and does not say anything about the plan's status. - A plan whose reasoning cannot be placed is not retired. If
there is no sensible home in
docs/for why the code is the shape it is, the plan is left where it is and reported, so that a person can decide. Deleting the only copy of a decision's justification to meet a 90-day rule is exactly the loss retirement exists to prevent. - It is never automatic. Retirement always goes through a
reviewed pull request: one per repository, one commit per plan,
merged by a person. It is deliberately not part of the
prune-reviewsworkflow, which pushes straight to the default branch and is safe only because what it does is computable. Deciding where a plan's reasoning belongs is not.
History¶
ryll's docs/plans/completed/ was an earlier approach: finished
phase files were moved there by hand and kept in the tree.
Retirement replaces it; the files in it retire like any others.
That is true of any local convention for finished plans: a
completed/ directory, a prose status, a per-repository rule. A
retirement that contradicts one reconciles it. The retirement wins,
and its commit says so.
The retire-plans skill in the private llm-setup repository does
this, one pull request per repository. Its retire-plans helper does
the parts with one right answer: listing eligible plans, finding
pointers, computing permalinks, rewriting the index row and checking
the result against the audit criteria above.