propagate-design-change skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys automation,workflow,systemoverrides

Propagate Design Change

When a GDD changes, architectural decisions written against it may no longer be valid. This skill finds every affected ADR, compares what the ADR assumed against what the GDD now says, and guides the user through resolution.

Usage: /propagate-design-change design/gdd/combat-system.md

Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automationalwaysask categories always prompt — ADR/schema impacts here fall under schemachanges and architecturedecisions).

Workflow tier: resolve for the changed GDD's system (per .claude/docs/workflow-modes.md): use the systemoverrides row for that system if the block lists one, else the project value. (A system pinned minimal has no ADRs even on a standard project — so its change is N/A.) It scopes the cascade: full cascades across all ADRs; standard checks only critical (Foundation-layer) ADRs plus any ADR referencing the changed GDD; minimal is not applicable** — no ADRs to cascade. See Step 4.

1. Validate Argument

A GDD path argument is required. If missing, fail with:

"Usage: /propagate-design-change design/gdd/[system].md

Provide the path to the GDD that was changed."

Verify the file exists. If not, fail with:

"[path] not found. Check the path and try again."

2. Diff the GDD Against Its Previous Version

Ask git what changed — do not read two whole documents and compare them by eye. The previous form of this step read the current GDD in full and git show-ed the full committed version, then diffed them mentally: two entire documents in context to find what is usually a handful of lines, and a model comparing 400-line documents will eventually miss an edit. Git cannot.

git diff HEAD -- design/gdd/[filename].md

If that is empty, the change may already be committed — widen to the commit that last touched it:

git diff HEAD~1 HEAD -- design/gdd/[filename].md

If the file has no git history (new file), report:

"No previous version in git — this appears to be a new GDD, not a revision.

Nothing to propagate."

If the diff is empty and the file has history, report that plainly — "no uncommitted or last-commit changes to [file]" — and ask which revision to propagate. An empty diff is not "no impact"; it means nothing changed here.

From the diff hunks:

changed acceptance criteria, changed tuning knobs). The @@ hunk headers name the enclosing section, so the changed-section list falls out of the diff itself.

• Identify sections that changed (new rules, removed rules, modified formulas,

small to interpret on its own (a changed number whose meaning depends on the rule above it). That is a targeted read of one section, not the document.

• Read the surrounding section from the current GDD only where a hunk is too

• Sections with no hunk are unchanged — by construction, not by inspection.

3. Produce the Change Summary

From the hunks resolved in step 2:

## Change Summary: [GDD filename]
Date of revision: [today]

Changed sections:
- [Section name]: [what changed — new rule, removed rule, formula modified, etc.]

Unchanged sections:
- [Section name]

Key changes affecting architecture:
- [Change 1 — likely to affect ADRs]
- [Change 2]

Downstream GDD impact via the registry. If design/registry/entities.yaml exists, it already records which other GDDs depend on this system's facts — compute the affected set from it rather than re-reading every GDD:

Grep pattern="source: design/gdd/[filename]" path="design/registry/entities.yaml" output_mode="content" -A 6

For each entity/constant/formula this GDD owns whose value the diff changed, its referencedby: list is the set of downstream GDDs that may now be inconsistent — report them under "Downstream GDDs to re-check". If design/registry/entities.yaml does not exist or has no entries** (it ships as an empty stub until /design-system populates it), skip this — the ADR cascade below still runs.

4. Load Architecture Inputs

Read ADRs in docs/architecture/ per the resolved tier:

that references the changed GDD.

• full — read all ADRs.
• standard — read only critical (Foundation-layer) ADRs plus any ADR

cascade at minimal workflow — design change recorded; no architecture impact analysis." and stop here.

• minimal — not applicable: there are no ADRs to cascade. Report "No ADR

Establish the denominator first. Glob the in-scope ADRs (per the tier above). Call the count N. If N is 0: "No ADRs found in docs/architecture/ — nothing to cascade." Stop.

Scan the requirement tables — do not full-read the ADRs at this step:

Grep pattern="## GDD Requirements Addressed" glob="docs/architecture/adr-*.md" output_mode="content" -A 15

Recall net — an ADR may cite the changed GDD in prose without tabling it:

Grep pattern="[changed-gdd-basename]" glob="docs/architecture/adr-*.md" output_mode="files_with_matches"

Take the union of the two results as the affected set M. This turns N × ~200 lines into N × ~15 lines; §5 full-reads only the M.

Interpret the result — a zero-match scan is never "no impact" by default:

Read docs/architecture/requirements-traceability.md if it exists.

Report: "Loaded [N] ADRs by scan. [M] reference [gdd filename] ([X] via requirements table, [Y] via prose reference only)."

5. Impact Analysis

Now read each ADR in the affected set M for its reasoning, not just its table — judging whether a decision is still valid needs the ADR's ## Context and ## Decision (and ## Consequences where present), not scan output. Do not attempt the judgement below from scan output.

This read is unbounded only up to a point — check size first (Bash: wc -c "docs/architecture/[adr-file].md"):

(Grep pattern="^## " path="docs/architecture/[adr-file].md" output_mode="content" -n), then bounded-Read only ## Context, ## Decision, and ## Consequences. An unbounded Read on a large ADR hits the 25k-token cap and, unrecovered, the only path forward is paging through the entire remainder — measured at 103k tokens on a 34k-token ADR, most of it content this analysis never uses.

• Under ~50KB — one full Read is fine and cheapest at this size.
• ~50KB or larger — map headings first

For each ADR that references the changed GDD:

Compare the ADR's "GDD Requirements Addressed" entries against the changed sections of the GDD. For each referenced requirement:

1. Locate the requirement in the current GDD — does it still exist?
2. Compare: What did the GDD say when the ADR was written vs. what it says now?
3. Assess the ADR decision: Is the architectural decision still valid?

Classify each affected ADR as one of:

For each affected ADR, produce an impact entry:

### ADR-NNNN: [title]
Status: [Still Valid / Needs Review / Likely Superseded]

What the ADR assumed about this GDD:
  "[relevant quote from the ADR's GDD Requirements Addressed section]"

What the GDD now says:
  "[relevant quote from the current GDD]"

Assessment:
  [Explanation of whether the ADR decision is still valid, and why]

Recommended action:
  [Keep as-is | Review and update | Mark Superseded and write new ADR]

6. Present Impact Report