Basinfy/Basinfy-SaaS-Studio / .agents/skills/saas-propagate-design-change
saas-propagate-design-change
UnverifiedTrace PRD changes across ADRs, stories, and code modules to resolve downstream impact.
Running this workflow on this client
Run commands from the project root (use Git Bash on Windows if bash points to an unavailable WSL distro). Shared studio files live in .claude/; follow .agents/PORTABLE-RUNTIME.md and .claude/docs/config-resolution.md for client tools, delegation, and approval rules.
Run bash .claude/hooks/yaml-helper.sh resolve_config --keys locale,review_mode,review_gate,automation,automation_always_ask,workflow,system_overrides and use its output below.
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
Locale & User Profile: Match
locale(pt-BR→ natural Brazilian Portuguese questions/options, overriding English examples;en→ English) anduser_profile(founder→ plain business language with(Recomendado)first, zero tech jargon;developer→ technical). Keep code/tests 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."
Basinfy Blast-Radius Graph: When
.basinfy/is present, runbasinfy_query_script(basinfy.discover+basinfy.impact) to trace real AST module dependents in 1 turn before falling back to text search.
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].mdprints 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 (thelayercolumn 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:
- each ADR's PRD Requirements Addressed section
(
bash .claude/scripts/md-section.sh extract <adr> "PRD Requirements Addressed"), for rows naming the changed PRD; - 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:
- Does the requirement still exist in the current PRD?
- What did the PRD say when the ADR was written, and what does it say now?
- 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 stateTD-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-changeagain to check coverage." - ADRs to update in place: the fields to change in each.
- Many ADRs affected: "Run
/saas-architecture-reviewonce 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |