Propagate Design ChangeSAFE

Turn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: propagate-design-change
description: "A GDD changed — scan ADRs and the traceability index for now-stale architectural decisions. Impact report, guides resolution."
argument-hint: "[path/to/changed-gdd.md] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/propagate-design-change/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,system_overrides`

Resolved above — use as-is; `--review` overrides `review_mode` for this run. No
block → defaults in `.claude/docs/config-resolution.md`.

# 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;
`automation_always_ask` categories always prompt — ADR/schema impacts here fall
under `schema_changes` and `architecture_decisions`).

**Workflow tier**: resolve for the **changed GDD's system** (per
`.claude/docs/workflow-modes.md`): use the
`system_overrides` 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.

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

```bash
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:
- Identify sections that changed (new rules, removed rules, modified formulas,
  changed acceptance criteria, changed tuning knobs). The `@@` hunk headers name
  the enclosing section, so the changed-section list falls out of the diff itself.
- Read the surrounding section from the current GDD **only** where a hunk is too
  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.
- 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 `referenced_by:` 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**:
- **`full`** — read **all** ADRs.
- **`standard`** — read only **critical (Foundation-layer) ADRs** plus any ADR
  that references the changed GDD. An ADR is critical when the `**Layer**` row of
  its `## Engine Compatibility` table says `Foundation`, or when it has no
  `**Layer**` row — when in doubt, treat it as critical
  (`.claude/docs/workflow-modes.md`). Read every row in one call:
  `Grep pattern="\*\*Layer\*\*" glob="docs/architecture/adr-*.md" output_mode="content"`,
  and count an ADR that Grep does not list as critical.
- **`minimal`** — **not applicable**: there are no ADRs to cascade. Report "No ADR
  cascade at minimal workflow — design change recorded; no architecture impact
  analysis." and stop here.

**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/arch

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.