Background
.docs-plan/decisions.md was introduced as a coordination tool during the initial docs restructuring and migration. Its purpose was to prevent agents and contributors from re-litigating structural choices mid-migration (directory layout, sidebar structure, file format defaults, sync strategies, etc.).
Current state
The migration is nearly complete. Two PRs remain before it can be considered done:
Proposed action
Once both PRs are merged, evaluate whether to:
-
Drop .docs-plan/decisions.md — at that point, the decisions are fully baked into the codebase. The structure itself is the record. Keeping the file adds maintenance overhead without value: new structural decisions should go in PR descriptions, not a separate log.
-
Update CLAUDE.md for maintenance mode — the current instruction "Read .docs-plan/decisions.md before proposing structural changes" should be replaced. In maintenance mode, agents should be pointed at the current directory structure and the "Ask first" list in CLAUDE.md instead.
-
Assess the rest of .docs-plan/ — migration-plan.md, synthesis.md, developer-journey.md etc. were also migration-phase artifacts. Decide which (if any) remain useful as evergreen references vs. which should be archived or removed.
Out of scope
content-authoring.md and review-guidelines.md are not migration-specific and should be kept regardless.
Background
.docs-plan/decisions.mdwas introduced as a coordination tool during the initial docs restructuring and migration. Its purpose was to prevent agents and contributors from re-litigating structural choices mid-migration (directory layout, sidebar structure, file format defaults, sync strategies, etc.).Current state
The migration is nearly complete. Two PRs remain before it can be considered done:
Proposed action
Once both PRs are merged, evaluate whether to:
Drop
.docs-plan/decisions.md— at that point, the decisions are fully baked into the codebase. The structure itself is the record. Keeping the file adds maintenance overhead without value: new structural decisions should go in PR descriptions, not a separate log.Update
CLAUDE.mdfor maintenance mode — the current instruction "Read.docs-plan/decisions.mdbefore proposing structural changes" should be replaced. In maintenance mode, agents should be pointed at the current directory structure and the "Ask first" list inCLAUDE.mdinstead.Assess the rest of
.docs-plan/—migration-plan.md,synthesis.md,developer-journey.mdetc. were also migration-phase artifacts. Decide which (if any) remain useful as evergreen references vs. which should be archived or removed.Out of scope
content-authoring.mdandreview-guidelines.mdare not migration-specific and should be kept regardless.