Retrofit doc-reconciliation playbook for common pre-existing layouts#49
Merged
Conversation
Capture three recurring reconciliation shapes (split architecture docs -> doc/architecture/; future-work/TODO/backlog -> roadmap; oversized CLAUDE.md -> slim to pointers) as durable, extensible guidance, framed as a seed set rather than a fixed algorithm. Hybrid placement, process-first: process doc §6 records them as the source of truth; template roadmap Phase 1 intro carries them where the target's first /cdd-next-step reconciliation session actually reads; cdd-retrofit.md §3.4 points at them to set expectations. Checks off the Phase 10 item. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
drabaioli
commented
Jul 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Captures the recurring doc-reconciliation fold-ins seen when retrofitting CDD onto real existing projects, so they aren't rediscovered each time. Adds a seed set (explicitly non-exhaustive) of common pre-existing-layout patterns in three consistent places:
claude-driven-development.md§6) — bulleted list of recurring shapes in the existing-project cost discussion.template/doc/knowledge_base/roadmap.md) — "Common fold-ins seen in practice" under the Phase 1 bootstrap intro, so the first/cdd-next-stepreconciliation session has them on hand./cdd-retrofitnext-steps bullet — points at the roadmap's Phase 1 seed set.The patterns: split architecture docs (
doc/backend/+doc/frontend/, a top-levelsystem-architecture.md) →doc/architecture/; afuture-work.md/TODO/backlog doc → the roadmap; an oversizedCLAUDE.mdduplicating command/troubleshooting content → slim to pointers.Ticks the corresponding roadmap item and completes the "pre-existing doc layout" milestone.
Verification
Doc-only change. All CI gates green:
bash -nacross scripts/tools/demo, command-drift-check, prompt-seam-check, install-smoke, worktree-resume, end-to-end bootstrap smoke, template-smoke assertions, demo seed-overlay. No upstream drift.Two-layer discipline satisfied (process doc + template both touched, process-first); template examples kept generic.
🤖 Generated with Claude Code