!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,automation_always_ask,workflow,system_overrides
Resolved above — use as-is; --review overrides review_mode for this run. No
block → defaults in .claude/docs/config-resolution.md.
Ask with the question tool. Without one, list the options numbered and end your turn
to wait. A skipped or dismissed question is not an answer: ask again in plain text.
Propagate Design Change
When a GDD changes, the architecture decisions written against it may no longer
hold. This skill finds every ADR the change touches, compares what the ADR assumed
with what the GDD says now, and walks the user through each one.
Example: /propagate-design-change design/gdd/combat-system.md
Asks follow .claude/docs/automation-modes.md (collaborative always asks, guided
asks on major choices, autonomous logs and goes on; automation_always_ask
categories always ask: an ADR impact here is schema_changes and
architecture_decisions).
Tier. workflow for the changed GDD's system: its system_overrides row if
there is one, else the project value. A system pinned minimal has no ADRs even on
a standard project. full checks every ADR; standard checks the critical
(Foundation-layer) ADRs and any ADR that names the changed GDD; minimal has
nothing to check (Phase 4).
Phase 1: The GDD path
The text typed after the skill name, with any --review <mode> pair removed, is the
changed GDD. It is required. Missing: "Usage: /propagate-design-change design/gdd/[system].md — give the path to the GDD that changed." Not a file:
"[path] not found. Check the path and try again."
Phase 2: What changed
Ask git, never compare two whole documents by eye:
git diff HEAD -- design/gdd/[filename].md
Empty: the change may be committed already, so widen to the last commit that
touched it: git diff HEAD~1 HEAD -- design/gdd/[filename].md.
- No history at all (
git log --oneline -1 -- design/gdd/[filename].md prints
nothing): "No previous version in git — this is a new GDD, not a revision.
Nothing to propagate." Stop.
- History, but both diffs empty: report "no uncommitted or last-commit changes to
[file]" and ask which revision to propagate. An empty diff means nothing changed
here, not that nothing is affected.
From the hunks: the @@ headers name the section each change sits in, so the
changed-section list comes from the diff itself. A section with no hunk is unchanged
by construction. Read the surrounding section only when a hunk cannot be understood
alone (a changed number whose meaning depends on the rule above it), and then only
that section: bash .claude/scripts/md-section.sh extract design/gdd/[file].md "[Section]".
Phase 3: The change summary
## Change Summary: [GDD filename]
Date of revision: [today]
Changed sections:
- [Section]: [what changed — new rule, removed rule, formula modified, …]
Unchanged sections:
- [Section]
Key changes affecting architecture:
- [change likely to affect ADRs]
Other GDDs that use these facts. When design/registry/entities.yaml does not
exist or has no entries (it ships as an empty stub until /design-system fills it),
skip this; the ADR check below still runs. Otherwise it records which GDDs depend on
this system's facts: search it for source: design/gdd/[filename]. For each entity, constant or formula this GDD owns
whose value the diff changed, its referenced_by: list names the GDDs that may now
disagree. List them under "Downstream GDDs to re-check".
Phase 4: The ADRs in scope
bash .claude/scripts/adr-status.sh lists every ADR with its status, layer and
missing sections.
full: every ADR.standard: the critical ones (the layer column reads Foundation, or holds
no layer: when in doubt, critical) and any ADR that names the changed GDD.minimal: report "No ADR check at minimal workflow — design change recorded;
no architecture impact analysis." Stop.
Establish the denominator first: their count is N. N is 0: "No ADRs found in docs/architecture/ — nothing to
check." Stop.
Which ones reference this GDD. Without reading whole ADRs:
- each ADR's GDD Requirements Addressed section
(
bash .claude/scripts/md-section.sh extract <adr> "GDD Requirements Addressed"),
for rows naming the changed GDD;
- a search of the ADRs for the changed GDD's file name, which catches an ADR that
cites it in prose without a table row.
The union of the two is the affected set M.
| Result | Meaning | Action |
|---|
| M ≥ 1 | Normal. | Go on. The N − M others are out of scope for this check: never describe them as verified unaffected. |
M = 0, and every in-scope ADR lacks GDD Requirements Addressed (missing column) | Traceability cannot be computed. | "[N] ADRs found, none has a 'GDD Requirements Addressed' section — traceability cannot be computed (a pre-production gate blocker). Run /architecture-decision retrofit [adr]." Stop. |
| M = 0, the sections exist | No ADR references this GDD. | "No ADR references [gdd] — no architecture impact." Stop. |
Read docs/architecture/requirements-traceability.md when it exists.
Report: "Checked [N] ADRs. [M] reference [gdd filename] ([X] in a requirements
table, [Y] in prose only)."
Phase 5: Impact analysis
For each ADR in M, read its Context, Decision and Consequences sections with
md-section.sh extract: whether a decision still holds needs its reasoning, never
only its table row. Then, for each requirement it lists from the changed GDD:
- Does the requirement still exist in the current GDD?
- What did the GDD say when the ADR was written, and what does it say now?
- Does the decision still hold?
Classify each ADR:
| Status | Meaning |
|---|
| ✅ Still Valid | The change does not touch what this ADR decided |
| ⚠️ Needs Review | The change may affect it; human judgement needed |
| 🔴 Likely Superseded | The change contradicts what this ADR assumed |
### ADR-NNNN: [title]
Status: [Still Valid | Needs Review | Likely Superseded]
What the ADR assumed about this GDD:
"[quote from its GDD Requirements Addressed or Context]"
What the GDD now says:
"[quote from the current GDD]"
Assessment:
[whether the decision still holds, and why]
Recommended action:
[Keep as-is | Review and update | Mark Superseded and write a new ADR]
Phase 6: The impact report, then the review
Show the whole report before asking for any action:
## Design Change Impact Report
GDD: [filename]
Date: [today]
Changes detected: [N sections changed]
ADRs referencing this GDD: [M]
### Not Affected
[ADRs whose decisions still hold]
### Needs Review ([count])
[ADRs that may need updating]
### Likely Superseded ([count])
[ADRs whose assumptions the change contradicts]
The technical review. Read the review_gate line above. skill-gates=skip
(solo or lean): no agent; note TD-CHANGE-IMPACT skipped — [Solo | Lean] mode.
skill-gates=run: hand the review to the technical-director agent with gate
TD-CHANGE-IMPACT (.claude/docs/director-gates/td-change-impact.md; the agent
reads it itself). Brief:
- Objective: check the impact report before the user acts on it.
- Give it: the whole report above: the change summary, every affected ADR with
its classification and recommended action.
- Check: no ADR is under-classified; the recommended actions are sound; no
knock-on effect on other ADRs or systems was missed.
- Return: APPROVE, CONCERNS, REJECT, or NOT ASSESSED naming a missing input.
- Boundaries: it edits no file.
Act on the verdict:
- APPROVE: go to Phase 7.
- CONCERNS: show the flagged ADRs or actions, and ask: "How do you want to go
on?" Options: Revise the impact assessment / Accept with the noted concerns /
Discuss further.
- REJECT: do not go to Phase 7; analyse the impact again first.
- NOT ASSESSED: it is not an approval (
.claude/docs/director-gates.md). Name
what was missing, then supply it and run the review again; or, when the user
chooses to go on without it, go to Phase 7 and state TD-CHANGE-IMPACT: NOT ASSESSED — [input] in the report and the final verdict line.
Phase 7: Resolve each ADR
For each ADR marked Needs Review or Likely Superseded, one at a time, ask: "ADR-NNNN
([title]) — [status]. What would you like to do?" Options:
- Mark it Superseded (I'll write the new ADR)
- Update it in place (a small revision): note what to revise; the user edits it
- Keep it as it is (the change does not affect this decision)
- Skip it for now (revisit later)
Mark Superseded. Ask "May I set the Status of [ADR file] to Superseded?" On yes,
replace only the body of its ## Status section:
bash .claude/scripts/md-section.sh replace docs/architecture/[adr-file].md "Status" <<'EOF'
Superseded — replacement pending (see docs/architecture/change-impact-[date]-[system-slug].md)
EOF
This is the one form this skill writes. adr-status.sh reads it as Superseded, so
/dev-story and /create-stories block the stories that still point at it. The
new ADR, once written, records which one it replaces. Change nothing else in the
ADR: its content stays.
Phase 8: The traceability index
When docs/architecture/requirements-traceability.md exists, ask "May I add the
changed requirements to the traceability index?" On yes, add a row per changed
requirement:
## Superseded Requirements
| Date | GDD | Requirement | Changed To | ADRs Affected | Resolution |
|------|-----|-------------|------------|---------------|------------|
| [date] | [gdd] | [old requirement text] | [new requirement text] | ADR-NNNN | [Superseded/Updated/Valid] |
Phase 9: The change impact document
Ask "May I write the change impact report to
docs/architecture/change-impact-[date]-[system-slug].md?" It holds the change
summary, the impact analysis, the resolution chosen for each ADR, and the ADRs that
need writing or updating.
Phase 10: Follow-up
From the resolutions:
- ADRs marked Superseded: "Run
/architecture-decision [title] to write the
replacement, then /propagate-design-change again to check coverage."
- ADRs to update in place: the fields to change in each.
- Many ADRs affected: "Run
/architecture-review once they are updated, to check
the traceability matrix still holds together."
End with Verdict: COMPLETE — change impact report saved after the Phase 9 write,
or Verdict: BLOCKED — user declined the write when declined.