Retrofit reconciles newly-added fill-in docs instead of shipping raw skeletons#43
Merged
Merged
Conversation
…skeletons (#41) In upgrade mode, files newer than the target's baseline are added. When such a file is a fill-in skeleton, its placeholder defaults make false claims about a mature project (the motivating case: engineering-practices.md landing with unfilled <test command>/<ci workflow> placeholders and provisional <Enforced once…> markers in a project already enforcing pytest, ruff, and CI). cdd-retrofit.md §4.4 now scans each staged added file for residual <...> tokens (genuine fill-in, since the render already substitutes the two identifiers), makes a best-effort reconciliation of the fields it can confidently detect from project state under the existing per-file approval, and §5 flags any file left with residual placeholders/provisional markers under a distinct 'added — needs reconciliation' category. Kept lightweight; /cdd-pre-pr stays the backstop. Install mode is exempt (whole template lands as skeleton by design). Process-first: the process doc's §6 existing-project section carries the matching sentence. Roadmap Phase 10 records what landed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The upgrade-mode bullet in doc/features/template.md summarized the three-way comparison but was silent on the newly-added-file case. Add a clause noting that files the template accrued since the baseline are reconciled rather than shipped raw, with residual-placeholder files flagged in the summary. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
In upgrade mode,
/cdd-retrofitcompares each CDD-managed file three ways against the baseline. A file the template has accrued since the target's baseline shows up as an add — and it may be a fill-in skeleton whose placeholder defaults make false claims about a mature project (the motivating case:engineering-practices.mdarriving with<test command>/<ci workflow>placeholders and provisional<Enforced once…>markers, claiming no gate exists in a project already running pytest, ruff, and CI).This change stops shipping those adds raw:
.claude/commands/cdd-retrofit.md§4.4 — for every proposed add, scan the staged render for residual<...>tokens (the two identifiers are already substituted, so anything left is genuine fill-in content). If present, make a lightweight best-effort reconciliation pass filling fields confidently detectable from the target's actual state, under the same per-file approval as any other write. Never fabricate a value; leave what you can't determine and let the summary flag it. Includes a workedengineering-practices.mdexample..claude/commands/cdd-retrofit.md§5 — new "Added — needs reconciliation" report category, distinct from clean adds, so residual-placeholder files read as an action item rather than a silent success./cdd-next-stepdoc-reconciliation task is the intended mechanism).doc/features/template.md— upgrade-mode bullet reconciled to reflect the added-skeleton behavior (pre-PR reconciliation).Best-effort by design;
/cdd-pre-prremains the systematic backstop.Testing
bash -nclean across scripts/tools/demoPrompt/doc-only change (interpreted by the LLM at retrofit time); no harness tests prompt semantics, and the structural seam/drift guardrails pass — matching the repo norm for prompt edits.
Closes #41
🤖 Generated with Claude Code