The Kirin System¶
Decision record: the plan archive¶
D-01 — The manual is canonical for current behaviour; the plan documents stay in place as the dated record of each decision as made
Context The project’s design rationale lived in fifteen PLAN.md files with no index, while the four LaTeX documents that were supposed to be the reference had not been updated in three months. Consolidating into one manual was straightforward; what to do with the plans was not, because roughly 118 source files cite them by path and section number.
Decision Absorb the plans’ content — descriptions and decision rationale alike — into this manual, and keep every PLAN.md in place, frozen, at its current path with its current section numbering.
Rejected Convert and delete was rejected because it invalidates all 118 citations at a stroke; a comment pointing at lichess-docs/PLAN.md §8 to explain a type’s shape is worthless if §8 no longer exists. Move to an archive directory fails for the same reason. Leave the plans as the only record was rejected because it is the status quo that produced the problem: no index, no single read-through, and rationale discoverable only by knowing which file to open.
Consequences Two artefacts describe each subsystem, so their roles must stay distinct: the manual is authoritative for what is true now, and an archived plan is authoritative for what was decided on its date. When they disagree, the code moved and the manual is right — that is the expected case, not a defect. The cost is that a subsystem change must update the manual chapter in the same commit, the same discipline the plans’ status headers already required.