Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/pipeline/propagate-design-change.md

Skill Test Spec: /propagate-design-change

Skill Summary

/propagate-design-change handles GDD revision cascades into the architecture. Given a changed GDD path, it asks git what changed (git diff HEAD, then the last commit), summarises the changed sections, checks the entity registry for downstream GDDs to re-check, then finds every ADR that references the GDD — by scanning ## GDD Requirements Addressed tables plus a prose grep for the GDD's basename — and reads only that affected set. Each affected ADR is classified Still Valid / Needs Review / Likely Superseded and the full Design Change Impact Report is shown before any action.

In full review mode the TD-CHANGE-IMPACT gate (technical-director) reviews the report before resolution; in lean/solo it is skipped with a note. The user then decides per ADR (Mark Superseded / Update in place / Keep as-is / Skip), and every file change — an ADR status line, the traceability index, the docs/architecture/change-impact-[date]-[system].md report — has its own ask. The cascade scope follows the changed system's workflow tier (full all ADRs, standard critical ADRs plus those referencing the GDD, minimal not applicable). Verdicts: COMPLETE (impact report saved) or BLOCKED (user declined the write).

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 phase headings
• Contains verdict keywords: COMPLETE, BLOCKED
• Contains "May I" ask-before-write language for each file it changes
• Has a next-step handoff at the end (/architecture-decision, /architecture-review)
• Documents that the impact report is shown before any change is made
• Documents gate TD-CHANGE-IMPACT: runs in full, skipped in lean/solo

---

Director Gate Checks

One gate: TD-CHANGE-IMPACT (technical-director, .claude/docs/director-gates/td-change-impact.md), spawned after the Design Change Impact Report is presented and before the per-ADR resolution workflow.

• full → spawned with the full impact report (change summary, classifications, recommended actions)
• lean → skipped; output notes "TD-CHANGE-IMPACT skipped — Lean mode."
• solo → skipped; output notes "TD-CHANGE-IMPACT skipped — Solo mode."

Verdict handling: APPROVE → resolution workflow; CONCERNS → AskUserQuestion with Revise the impact assessment / Accept with noted concerns / Discuss further; REJECT → no resolution; the impact is re-analysed first; NOT ASSESSED [missing input] → never read as APPROVE: the input is supplied and the gate re-run, or the run goes on with TD-CHANGE-IMPACT: NOT ASSESSED — [input] stated in the report and the Verdict line.

---

Test Cases

Case 1: Happy Path — GDD formula change affects one of two referencing ADRs

Fixture:

• project.yaml: modes.workflow: full, modes.review_mode: lean
• design/gdd/combat.md has an uncommitted edit to a damage formula in its Formulas section
• docs/architecture/ has 4 ADRs; ADR-0003 and ADR-0005 list combat.md in ## GDD Requirements Addressed; ADR-0003's decision assumed the old formula, ADR-0005's decision does not depend on it
• docs/architecture/requirements-traceability.md exists

Input: /propagate-design-change design/gdd/combat.md

Expected behavior:

1. Verifies the file exists; runs git diff HEAD -- design/gdd/combat.md and derives the changed sections from the hunks
2. Prints the Change Summary (changed / unchanged sections, key changes)
3. Globs the ADRs (N = 4), greps the requirement tables and the combat basename, and reports "Loaded 4 ADRs by scan. 2 reference combat.md (…)"
4. Reads ADR-0003 and ADR-0005 (size checked with wc -c first) and classifies ADR-0003 Needs Review or Likely Superseded, ADR-0005 Still Valid
5. Presents the Design Change Impact Report
6. Notes "TD-CHANGE-IMPACT skipped — Lean mode."
7. Asks "ADR-0003 ([title]) — [status]. What would you like to do?" with the four options; no resolution ask for ADR-0005
8. Asks "May I update the traceability index?" and "May I write the change impact report to docs/architecture/change-impact-[date]-combat.md?"
9. Verdict: COMPLETE — change impact report saved

Assertions:

• What changed is taken from git diff, not from reading two whole documents
• Only the 2 referencing ADRs are full-read; the other 2 are not described as verified unaffected
• The full impact report is shown before any resolution ask or write
• A resolution ask is made per Needs Review / Likely Superseded ADR, one at a time
• Each file change (ADR status, traceability index, impact report) has its own ask
• "TD-CHANGE-IMPACT skipped — Lean mode." appears
• Verdict is COMPLETE after the impact report is written

---

Case 2: Zero matches — "no impact" versus "cannot trace"

Fixture (tables present):

• project.yaml: modes.workflow: full
• design/gdd/combat.md has an uncommitted edit
• 3 ADRs, each with a ## GDD Requirements Addressed section, none naming combat.md in the table or in prose

Input (both fixtures): /propagate-design-change design/gdd/combat.md

Expected behavior (tables present):

1. Both scans return 0 with N = 3
2. The files-with-matches check for ## GDD Requirements Addressed is non-empty
3. Reports "No ADR references combat.md — no architecture impact."

Fixture (tables absent):

• Same GDD edit; 3 ADRs, none containing a ## GDD Requirements Addressed section and none naming combat.md

Expected behavior (tables absent):

1. Both scans return 0 with N = 3; the section check is also empty
2. Reports "3 ADRs found, none contains a 'GDD Requirements Addressed' section — traceability cannot be computed (a gate-pre-production blocker). Run /architecture-decision retrofit [adr]."

Assertions:

• With tables present, the "no architecture impact" message is printed
• With tables absent, the skill does NOT report "no impact" — it reports that traceability cannot be computed and names /architecture-decision retrofit [adr], the form that skill parses
• No per-ADR resolution ask and no ADR edit happens in either fixture
• Skill does NOT error or crash when no references are found

---

Case 3: Edge Case — Empty diff on a GDD with history

Fixture:

• project.yaml: modes.workflow: full
• design/gdd/combat.md is committed, has no uncommitted changes, and was not touched by the last commit

Input: /propagate-design-change design/gdd/combat.md

Expected behavior:

1. git diff HEAD -- design/gdd/combat.md is empty
2. git diff HEAD~1 HEAD -- design/gdd/combat.md is also empty
3. Reports "no uncommitted or last-commit changes to design/gdd/combat.md" and asks which revision to propagate
4. Does not report "no impact" and does not scan ADRs before a revision is chosen

Assertions:

• Both diffs are tried, working tree first, then the last commit
• The "no uncommitted or last-commit changes" report is printed
• The user is asked which revision to propagate
• The empty diff is NOT reported as "no impact"

---

Case 4: Edge Case — No argument provided

Fixture:

• Multiple GDDs exist in design/gdd/

Input: /propagate-design-change (no argument)

Expected behavior:

1. Skill detects no argument is provided
2. Skill fails with: "Usage: /propagate-design-change design/gdd/[system].md Provide the path to the GDD that was changed."
3. No diff, scan or analysis is performed

Assertions:

• Skill outputs the usage message when no argument is given
• The usage example shows the design/gdd/[system].md path format
• No git diff or ADR scan is performed without a target GDD
• Skill does NOT silently pick a GDD without user input

---

Case 5: Director Gate — TD-CHANGE-IMPACT returns CONCERNS in full mode

Fixture:

• project.yaml: modes.workflow: full, modes.review_mode: full
• A GDD edit that leaves one referencing ADR classified Needs Review
• TD-CHANGE-IMPACT returns CONCERNS: a second ADR was under-classified

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

Expected behavior:

1. The Design Change Impact Report is presented
2. technical-director is spawned via Agent with gate TD-CHANGE-IMPACT, passing the full report
3. CONCERNS are surfaced, naming the flagged ADR
4. AskUserQuestion: Revise the impact assessment / Accept with noted concerns / Discuss further
5. The per-ADR resolution workflow starts only after that answer

Assertions:

• TD-CHANGE-IMPACT is spawned after the impact report is shown and before any resolution ask
• The gate receives the full report (change summary, classifications, recommended actions)
• The CONCERNS name the flagged ADR and all three options are offered
• No ADR, traceability or report file is written before the CONCERNS are answered
• No "TD-CHANGE-IMPACT skipped" note appears in full mode

---

Case 6: Workflow tiers — minimal stops before the cascade; standard narrows it

Fixture (minimal):

• project.yaml sets no modes keys — modes.rigor defaults to minimal, so the workflow resolves to minimal
• design/gdd/loot.md has an uncommitted edit

Fixture (standard):

• project.yaml: modes.workflow: standard, modes.review_mode: solo
• design/gdd/loot.md has an uncommitted edit
• 4 ADRs, by their Engine Compatibility Layer: ADR-0001 (Foundation, event bus, no mention of loot.md), ADR-0002 (Foundation, save system, lists loot.md in ## GDD Requirements Addressed), ADR-0006 (Feature, loot tables, names loot.md in prose only), ADR-0007 (Feature, enemy AI, no mention)

Input (both fixtures): /propagate-design-change design/gdd/loot.md

Expected behavior (minimal):

1. The diff and Change Summary run as usual
2. At the ADR step: "No ADR cascade at minimal workflow — design change recorded; no architecture impact analysis." and the skill stops

Expected behavior (standard):

1. The in-scope set is the Foundation ADRs plus any ADR referencing loot.md: ADR-0001, ADR-0002 and ADR-0006, so N = 3; ADR-0007 is out of scope
2. Reports "Loaded 3 ADRs by scan. 2 reference loot.md (1 via requirements table, 1 via prose reference only)."
3. Full-reads only ADR-0002 and ADR-0006; notes "TD-CHANGE-IMPACT skipped — Solo mode."

Assertions:

• Minimal: no ADR is globbed or read, no gate is spawned or noted, and no write ask is made
• Standard: ADR-0007 is not counted or read, and neither it nor ADR-0001 is described as verified unaffected
• Standard: the prose-only reference in ADR-0006 is caught by the basename grep
• Standard: the Foundation ADRs are found from the **Layer** rows (Grep pattern="\*\*Layer\*\*" glob="docs/architecture/adr-*.md"), not guessed from titles
• Variant — ADR-0007 has no **Layer** row: it is treated as critical (when in doubt, critical) and joins the in-scope set, so N = 4

---

Protocol Compliance

• Diffs the GDD and scans ADRs before producing the impact report
• Impact report shown in full before any resolution ask
• Resolution asked per ADR — never one decision for the whole set
• "May I" asked before each file change; ADR content is never deleted, only marked Superseded
• TD-CHANGE-IMPACT runs in full, skipped with a named note in lean/solo
• Ends with follow-up actions matching the resolutions (/architecture-decision for Superseded ADRs, /architecture-review when many are affected)

---

Coverage Notes

• A system pinned minimal through system_overrides on a standard project (its change is N/A) is not given its own fixture; Case 6 reaches minimal through the project default.
• Downstream GDD impact via design/registry/entities.yaml is not independently fixture-tested.
• A GDD with no git history ("appears to be a new GDD, not a revision") and a path that does not exist are not separately tested.
• TD-CHANGE-IMPACT APPROVE, REJECT and NOT ASSESSED paths are not separately tested.
• Stories and epics are outside this skill's scope — it cascades into ADRs and the traceability index only.