Retrofit doc-reconciliation playbook for common pre-existing layouts

.claude/commands/cdd-retrofit.md

@@ -105,7 +105,7 @@ Walk every file in `$STAGE/render`. All writes go into `$WT` (the isolated workt
   ```
 
   Stage with `add -A` — the worktree was fresh, so this captures exactly the retrofit's writes. Gitignored paths won't be staged (see the section 1 gitignore warning). Commit only on this dedicated branch; never commit onto the target's existing branches.
-- Print next steps: the one-time worktree-helper install (`./tools/cdd-worktree.sh install` in the CDD repo — project-independent, only needed if the user hasn't installed it before; nothing is added per project); how to review and merge the branch (`git -C "$WT" show`, then — before opening the PR — `cd "$WT"` and start a fresh Claude session there to run `/cdd-pre-pr`, which reconciles and reviews the retrofit's own edits and catches doc skeletons left with unfilled placeholders; then open a PR from `cdd-retrofit`); and that once merged they can remove the worktree with `git -C <target> worktree remove "$WT"`. Then run `/cdd-next-step` in the target — it will pick up the roadmap's pre-filled bootstrap tasks (codebase survey, initial architecture and feature docs, CLAUDE.md stubs, roadmap fill) as the first task. Warn the user: on an existing project without prior doc discipline this first task is a doc reconciliation that forces the docs to match the code for the first time, so it may be slow and span several early PRs — that is expected, not a fault. Where docs already exist, it reconciles and adopts them rather than overwriting.
+- Print next steps: the one-time worktree-helper install (`./tools/cdd-worktree.sh install` in the CDD repo — project-independent, only needed if the user hasn't installed it before; nothing is added per project); how to review and merge the branch (`git -C "$WT" show`, then — before opening the PR — `cd "$WT"` and start a fresh Claude session there to run `/cdd-pre-pr`, which reconciles and reviews the retrofit's own edits and catches doc skeletons left with unfilled placeholders; then open a PR from `cdd-retrofit`); and that once merged they can remove the worktree with `git -C <target> worktree remove "$WT"`. Then run `/cdd-next-step` in the target — it will pick up the roadmap's pre-filled bootstrap tasks (codebase survey, initial architecture and feature docs, CLAUDE.md stubs, roadmap fill) as the first task. Warn the user: on an existing project without prior doc discipline this first task is a doc reconciliation that forces the docs to match the code for the first time, so it may be slow and span several early PRs — that is expected, not a fault. Where docs already exist, it reconciles and adopts them rather than overwriting; the roadmap's Phase 1 intro carries a seed set of common fold-in patterns (split architecture docs → `doc/architecture/`, a `future-work.md`/TODO/backlog doc → the roadmap, an oversized `CLAUDE.md` → slim to pointers) so the reconciliation session has them on hand.
 
 ## 4. Upgrade mode
 

doc/knowledge_base/claude-driven-development.md

@@ -476,7 +476,13 @@ In both modes the retrofit isolates its writes from the target's current branch.
 
 The doc-reconciliation discipline remains the bigger ask, and it is where retrofitting actually costs. The `/cdd-retrofit` session itself is cheap — it installs or upgrades files. The cost lands on the **first few PRs afterward**, as the project's architecture and feature docs are forced to reflect reality for the first time. That reconciliation is deliberately not done during `/cdd-retrofit`: that session is context-heavy, and surveying what the docs do and don't say needs its own focused session. So it is deferred to the project's first `/cdd-next-step`, which picks up the template roadmap's pre-filled "CDD bootstrap" phase (survey the codebase, draft the architecture and feature docs, fill the roadmap). For a greenfield project those tasks are near-trivial; for an existing project without prior doc discipline they are the opposite, and they may span several heavier-than-usual early PRs before the docs and the code agree.
 
-Two things temper this. First, the don't-disrupt-existing-docs stance: a retrofitted project often already has *some* documentation, and the first reconciliation should reconcile and adopt it into CDD's structure rather than overwrite it into the template layout. This is guidance, not an algorithm — the point is to preserve what the project already knows about itself, not to follow a fixed merge procedure. Second, the cost is a **first-time** cost. An upgrade retrofit (a project already running CDD) can assume the discipline already holds: its docs already track the code, so the heavy reconciliation does not recur. Only a first-time install faces the full bill. The command does not try to detect prior discipline beyond the install-vs-upgrade mode it already distinguishes; the two paths are described so the human knows which one they are on.
+Two things temper this. First, the don't-disrupt-existing-docs stance: a retrofitted project often already has *some* documentation, and the first reconciliation should reconcile and adopt it into CDD's structure rather than overwrite it into the template layout. This is guidance, not an algorithm — the point is to preserve what the project already knows about itself, not to follow a fixed merge procedure. Recurring shapes seen in practice (a seed set, not exhaustive):
+
+- `doc/backend/` + `doc/frontend/` + a top-level `system-architecture.md` → `doc/architecture/`
+- `future-work.md` / TODO / backlog doc → `roadmap.md`
+- an oversized `CLAUDE.md` duplicating command/troubleshooting content → slim to pointers (per-session context cost)
+
+Second, the cost is a **first-time** cost. An upgrade retrofit (a project already running CDD) can assume the discipline already holds: its docs already track the code, so the heavy reconciliation does not recur. Only a first-time install faces the full bill. The command does not try to detect prior discipline beyond the install-vs-upgrade mode it already distinguishes; the two paths are described so the human knows which one they are on.
 
 ## 7. Template directory layout
 

doc/knowledge_base/roadmap.md

@@ -134,7 +134,7 @@ Defects and gaps surfaced by retrofitting CDD onto real existing projects. Each
 - [x] **`cdd-next-step.md` hardcodes `~/Code/<PROJECT_DIR>` as the repo location** (the suggested source line). Fixed: `cdd-next-step.md` §8 now instructs resolving the repo root via `git rev-parse --show-toplevel` and embedding the actual path in the printed source line.
 - [ ] **Gitflow case: platform default ≠ integration branch** (e.g. `main` is the release branch but daily work branches off `devel`). `cdd-merge-base` and `cdd-pre-pr` target the platform default branch — correct for the PyGroundControl case (`devel` *is* the platform default), but wrong for gitflow projects where the platform default is the release branch. Fix requires an explicit `BASE_BRANCH` config mechanism.
 - [x] **Retrofit reconciles newly-added fill-in docs instead of shipping raw skeletons.** In upgrade mode, when a template file newer than the target's baseline is added, retrofit reconciles obvious fields against detected project state under per-file approval, and flags any residual placeholders/provisional markers in the summary as "needs reconciliation" (issue #41). Fixed a Scribe upgrade landing `engineering-practices.md` with unfilled `<test command>`/`<ci workflow>` placeholders and provisional `<Enforced once…>` markers, factually wrong for a project already enforcing pytest, ruff, and CI. Install mode stays exempt (whole template lands as skeleton by design). Changes: `.claude/commands/cdd-retrofit.md` §4.4/§5 and the process doc's §6 existing-project section.
-- [ ] **Retrofit doc-reconciliation playbook for common pre-existing layouts.** PyGroundControl needed manual reconciliation that recurs across projects: a split architecture-doc layout (`doc/backend/`, `doc/frontend/`, a top-level `system-architecture.md`) folding into `doc/architecture/`; a `future-work.md`/TODO/backlog doc folding into `roadmap.md`; an oversized CLAUDE.md duplicating command/troubleshooting content that should be slimmed to pointers (per-session context cost). Capture these as explicit guidance/checklist in `/cdd-retrofit` (and the process doc's existing-project section) so they aren't rediscovered each time.
+- [x] **Retrofit doc-reconciliation playbook for common pre-existing layouts.** PyGroundControl needed manual reconciliation that recurs across projects: a split architecture-doc layout (`doc/backend/`, `doc/frontend/`, a top-level `system-architecture.md`) folding into `doc/architecture/`; a `future-work.md`/TODO/backlog doc folding into `roadmap.md`; an oversized CLAUDE.md duplicating command/troubleshooting content that should be slimmed to pointers (per-session context cost). Capture these as explicit guidance/checklist in `/cdd-retrofit` (and the process doc's existing-project section) so they aren't rediscovered each time.
 
 **Milestone:** CDD retrofits cleanly onto a project regardless of default-branch name, repo directory name/location, or pre-existing doc layout, without per-project manual fixes to the scaffolding.
 

template/doc/knowledge_base/roadmap.md

@@ -6,7 +6,11 @@ This file is the central artifact of the Claude-Driven Development workflow. It
 
 ## Phase 1: CDD bootstrap
 
-Get the CDD substrate to reflect reality: survey what exists, write the initial docs, and turn this file into a real plan. On a greenfield project some of these tasks are near-trivial — do the thin version and move on. On an existing project retrofitted onto CDD without prior doc discipline they are the opposite of trivial: this is the first time the docs are forced to match the code, and it may take several heavier-than-usual PRs before they agree. That cost is expected, not a sign anything is wrong. Where the project already has documentation, reconcile and adopt it into this structure rather than overwriting it — preserve what the project already knows about itself.
+Get the CDD substrate to reflect reality: survey what exists, write the initial docs, and turn this file into a real plan. On a greenfield project some of these tasks are near-trivial — do the thin version and move on. On an existing project retrofitted onto CDD without prior doc discipline they are the opposite of trivial: this is the first time the docs are forced to match the code, and it may take several heavier-than-usual PRs before they agree. That cost is expected, not a sign anything is wrong. Where the project already has documentation, reconcile and adopt it into this structure rather than overwriting it — preserve what the project already knows about itself. Common fold-ins seen in practice:
+
+- Split architecture docs (e.g. `doc/backend/` + `doc/frontend/`, a top-level `system-architecture.md`) → `doc/architecture/`.
+- A `future-work.md` / TODO / backlog doc → this roadmap.
+- An oversized `CLAUDE.md` duplicating command/troubleshooting content → slim to pointers (it costs context every session).
 
 - [ ] Survey the codebase and draft the initial architecture docs under `doc/architecture/`: an `overview.md` with the high-level shape, plus per-topic docs as warranted. For a greenfield project, write architecture guidelines and intentions instead. Where architecture notes already exist (a README, design docs), fold them in rather than starting from scratch.
 - [ ] Write the initial feature docs under `doc/features/`: one doc per existing user-visible capability. Likely empty for a greenfield project. Where features are already documented elsewhere, adopt and reconcile that content here.