propagate-design-change

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

```bash
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] 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:

1. Does the requirement still exist in the current GDD?
2. What did the GDD say when the ADR was written, and what does it say now?
3. 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:

```markdown
## 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.

Shown under the source repo’s MIT license. Read the full folder on GitHub.