Propagate Design Change

職業

カテゴリ

プロジェクト管理

Run git to get the previous committed version:

git show 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 git returns the previous version, do a conceptual diff:

• Identify sections that changed (new rules, removed rules, modified formulas, changed acceptance criteria, changed tuning knobs)
• Identify sections that are unchanged
• Produce a change summary:

## 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]

4. Load Architecture Inputs

Read all ADRs in docs/architecture/:

• For each ADR, read the full file
• Extract the "GDD Requirements Addressed" table
• Note which GDD documents and requirement IDs each ADR references

Read docs/architecture/architecture-traceability.md if it exists.

Report: "Loaded [N] ADRs. [M] reference [gdd filename]."

5. Impact Analysis

For each ADR that references the changed GDD:

Compare the ADR's "GDD Requirements Addressed" entries against the changed sections of the GDD. For each referenced requirement:

1. Locate the requirement in the current GDD — does it still exist?
2. Compare: What did the GDD say when the ADR was written vs. what it says now?
3. Assess the ADR decision: Is the architectural decision still valid?

Classify each affected ADR as one of:

For each affected ADR, produce an impact entry:

### ADR-NNNN: [title]
Status: [Still Valid / Needs Review / Likely Superseded]

What the ADR assumed about this GDD:
  "[relevant quote from the ADR's GDD Requirements Addressed section]"

What the GDD now says:
  "[relevant quote from the current GDD]"

Assessment:
  [Explanation of whether the ADR decision is still valid, and why]

Recommended action:
  [Keep as-is | Review and update | Mark Superseded and write new ADR]

6. Present Impact Report

Present the full impact report to the user before asking for any action. Format:

## Design Change Impact Report
GDD: [filename]
Date: [today]
Changes detected: [N sections changed]
ADRs referencing this GDD: [M]

### Not Affected
[ADRs referencing this GDD whose decisions remain valid]

### Needs Review ([count])
[ADRs that may need updating]

### Likely Superseded ([count])
[ADRs whose assumptions are now contradicted]

6b. Director Gate — Technical Impact Review

Review mode check — apply before spawning TD-CHANGE-IMPACT:

• solo → skip. Note: "TD-CHANGE-IMPACT skipped — Solo mode." Proceed to Phase 7.
• lean → skip. Note: "TD-CHANGE-IMPACT skipped — Lean mode." Proceed to Phase 7.
• full → spawn as normal.

Spawn technical-director via Task using gate TD-CHANGE-IMPACT (.claude/docs/director-gates.md).

Pass: the full Design Change Impact Report from Phase 6 (change summary, all affected ADRs with their Still Valid / Needs Review / Likely Superseded classifications, and recommended actions).

The technical-director reviews whether:

• The impact classifications are correct (no ADRs under-classified)
• The recommended actions are architecturally sound
• Any cascading effects on other ADRs or systems were missed

Apply the verdict:

• APPROVE → proceed to Phase 7 resolution workflow
• CONCERNS → surface the specific ADRs or recommendations flagged; use AskUserQuestion with options: Revise the impact assessment / Accept with noted concerns / Discuss further
• REJECT → do not proceed to resolution; re-analyze the impact before continuing

7. Resolution Workflow

For each ADR marked "Needs Review" or "Likely Superseded", ask the user what to do:

Ask for each ADR in turn:

"ADR-NNNN ([title]) — [status]. What would you like to do?" Options:

• "Mark Superseded (I'll write a new ADR)" — updates ADR status line to Superseded by: [pending]
• "Update in place (minor revision)" — opens the ADR for editing; note what to revise
• "Keep as-is (the change doesn't actually affect this decision)"
• "Skip for now (revisit later)"

For ADRs marked Superseded:

• Update the ADR's Status field: Superseded by ADR-[next number] (pending — see change-impact-[date]-[system].md)
• Ask: "May I update the status in [ADR filename]?"

8. Update Traceability Index

If docs/architecture/architecture-traceability.md exists:

• Add the changed GDD requirements to the "Superseded Requirements" table:

## Superseded Requirements
| Date | GDD | Requirement | Changed To | ADRs Affected | Resolution |
|------|-----|-------------|------------|---------------|------------|
| [date] | [gdd] | [old requirement text] | [new requirement text] | ADR-NNNN | [Superseded/Updated/Valid] |

Ask: "May I update the traceability index?"

9. Output Change Impact Document

Ask: "May I write the change impact report to docs/architecture/change-impact-[date]-[system-slug].md?"

The document contains:

• The change summary from step 3
• The full impact analysis from step 5
• Resolution decisions made in step 7
• List of ADRs that need to be written or updated

If user approved: Verdict: COMPLETE — change impact report saved. If user declined: Verdict: BLOCKED — user declined write.

10. Follow-Up Actions

Based on the resolution decisions, suggest:

• ADRs marked Superseded: "Run /architecture-decision [title] to write the replacement ADR. Then re-run /propagate-design-change to verify coverage."
• ADRs to update in place: List the specific fields to update in each ADR
• If many ADRs affected: "Run /architecture-review after all ADRs are updated to verify the full traceability matrix is still coherent."

Collaborative Protocol

1. Read silently — compute the full impact before presenting anything
2. Show the full report first — let the user see the scope before asking for action
3. Ask per-ADR — don't batch decisions; each affected ADR may need different treatment
4. Ask before writing — always confirm before modifying any file
5. Non-destructive — never delete ADR content; only add "Superseded by" notes