diff --git a/.claude/commands/cdd-retrofit.md b/.claude/commands/cdd-retrofit.md index 1798600..aaaa0c3 100644 --- a/.claude/commands/cdd-retrofit.md +++ b/.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 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 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 diff --git a/doc/knowledge_base/claude-driven-development.md b/doc/knowledge_base/claude-driven-development.md index da99003..9430164 100644 --- a/doc/knowledge_base/claude-driven-development.md +++ b/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 diff --git a/doc/knowledge_base/roadmap.md b/doc/knowledge_base/roadmap.md index 352566b..780a74e 100644 --- a/doc/knowledge_base/roadmap.md +++ b/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/` 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 ``/`` placeholders and provisional `` 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. diff --git a/template/doc/knowledge_base/roadmap.md b/template/doc/knowledge_base/roadmap.md index f968d89..97b9d8b 100644 --- a/template/doc/knowledge_base/roadmap.md +++ b/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.