/propagate-design-change

name: propagate-design-change
description: "Finds architecture decisions (ADRs) made stale by a changed GDD and walks through resolving each. Use when the user changed a number or rule in a GDD and asks which ADRs or architecture decisions are now out of date."
argument-hint: "[path/to/changed-gdd.md] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/propagate-design-change/../../hooks/yaml-helper.sh" resolve_config *), Bash(git diff *), Bash(git log *), Bash(bash .claude/scripts/adr-status.sh*), Bash(bash .claude/scripts/md-section.sh *)
model: sonnet

!`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:

1. each ADR's GDD Requirements Addressed section (`bash .claude/scripts/md-section.sh extract <adr> "GDD Requirements Addressed"`), for rows naming the changed GDD; 2. 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]