Scenario
The design/plan are written and scope-locked, then implementation proceeds. During execution the agent makes legitimate in-scope refinements — a config key gets a different (convention-conforming) name, an example command or code/DDL snippet changes, an identifier format is adjusted. These are not disproved assumptions (so scope-lock's design-backport path never triggers) and they don't change the manifest — they're routine accuracy drift.
Nothing in the pipeline reconciles the design doc with what was actually built, so by review time the design doc still describes the old names/examples. Across two features this produced repeated review comments: the same config key shown in snake_case in docs but camelCase in code (flagged across three files), and several "design no longer matches implementation" comments.
A related, narrower gap: the plan-phase adversarial-design-review doesn't check that config keys / command examples / flags in the plan match the repo's established naming convention and the identifiers the code will actually use. That one check would have caught the naming drift before a line of code was written.
Impact
- Design docs become stale-on-arrival; reviewers burn cycles on doc-vs-code drift instead of substance.
- The drift is predictable and mechanical — a good fit for an automated gate.
Recommendation
- Add a "design-sync" checkpoint — e.g. in
subagent-driven-development after each task group, or in finishing-a-development-branch before PR creation — that reconciles the design doc's concrete identifiers/examples (config keys, flags, DDL/code snippets, formats) with the implemented code. This is distinct from scope-lock's assumption-backport path (which is for disproved assumptions, not routine accuracy drift).
- Add a bug-class/check item to
adversarial-design-review (plan phase): "config keys, flags, env vars, and command/code examples in the plan match the implemented identifiers and the repo's established naming convention."
Scenario
The design/plan are written and scope-locked, then implementation proceeds. During execution the agent makes legitimate in-scope refinements — a config key gets a different (convention-conforming) name, an example command or code/DDL snippet changes, an identifier format is adjusted. These are not disproved assumptions (so
scope-lock's design-backport path never triggers) and they don't change the manifest — they're routine accuracy drift.Nothing in the pipeline reconciles the design doc with what was actually built, so by review time the design doc still describes the old names/examples. Across two features this produced repeated review comments: the same config key shown in snake_case in docs but camelCase in code (flagged across three files), and several "design no longer matches implementation" comments.
A related, narrower gap: the plan-phase
adversarial-design-reviewdoesn't check that config keys / command examples / flags in the plan match the repo's established naming convention and the identifiers the code will actually use. That one check would have caught the naming drift before a line of code was written.Impact
Recommendation
subagent-driven-developmentafter each task group, or infinishing-a-development-branchbefore PR creation — that reconciles the design doc's concrete identifiers/examples (config keys, flags, DDL/code snippets, formats) with the implemented code. This is distinct fromscope-lock's assumption-backport path (which is for disproved assumptions, not routine accuracy drift).adversarial-design-review(plan phase): "config keys, flags, env vars, and command/code examples in the plan match the implemented identifiers and the repo's established naming convention."