!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys locale,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

Interaction Localization Rule: When locale: pt-BR (or user speaks Portuguese), ALL questions (AskUserQuestion / ask_question), confirmation prompts, and selectable options MUST be translated and presented in Brazilian Portuguese (PT-BR). Any English question text or options in this skill are illustrative examples — NEVER display English questions or options to a Portuguese developer. Internal reasoning, code synthesis, tests, and documentation files MUST remain in English.

When a PRD 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 PRD says now, and walks the user through each one.

Example: /saas-propagate-design-change design/prd/billing-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 PRD'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 PRD; minimal has nothing to check (Phase 4).

Phase 1: The PRD path

The text typed after the skill name, with any --review <mode> pair removed, is the changed PRD. It is required. Missing: "Usage: /saas-propagate-design-change design/prd/[system].md — give the path to the PRD 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/prd/[filename].md

Empty: the change may be committed already, so widen to the last commit that touched it: git diff HEAD~1 HEAD -- design/prd/[filename].md.

• No history at all (git log --oneline -1 -- design/prd/[filename].md prints nothing): "No previous version in git — this is a new PRD, 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/prd/[file].md "[Section]".

Phase 3: The change summary

## Change Summary: [PRD 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 PRDs that use these facts. When design/registry/entities.yaml does not exist or has no entries (it ships as an empty stub until /saas-design-system fills it), skip this; the ADR check below still runs. Otherwise it records which PRDs depend on this system's facts: search it for source: design/prd/[filename]. For each entity, constant or formula this PRD owns whose value the diff changed, its referenced_by: list names the PRDs that may now disagree. List them under "Downstream PRDs 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 PRD.
• 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 PRD. Without reading whole ADRs:

1. each ADR's PRD Requirements Addressed section (bash .claude/scripts/md-section.sh extract <adr> "PRD Requirements Addressed"), for rows naming the changed PRD;
2. a search of the ADRs for the changed PRD'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 PRD Requirements Addressed (missing column)	Traceability cannot be computed.	"[N] ADRs found, none has a 'PRD Requirements Addressed' section — traceability cannot be computed (a pre-production gate blocker). Run /saas-architecture-decision retrofit [adr]." Stop.
M = 0, the sections exist	No ADR references this PRD.	"No ADR references [prd] — no architecture impact." Stop.

Read docs/architecture/requirements-traceability.md when it exists.

Report: "Checked [N] ADRs. [M] reference [prd 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 PRD:

1. Does the requirement still exist in the current PRD?
2. What did the PRD 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 PRD:
  "[quote from its PRD Requirements Addressed or Context]"

What the PRD now says:
  "[quote from the current PRD]"

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
PRD: [filename]
Date: [today]
Changes detected: [N sections changed]
ADRs referencing this PRD: [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 /saas-dev-story and /saas-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 | PRD | Requirement | Changed To | ADRs Affected | Resolution |
|------|-----|-------------|------------|---------------|------------|
| [date] | [prd] | [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 /saas-architecture-decision [title] to write the replacement, then /saas-propagate-design-change again to check coverage."
• ADRs to update in place: the fields to change in each.
• Many ADRs affected: "Run /saas-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.