# ICIAS Impact Analysis Protocol

Full protocol for Change Impact Analysis on PRD sessions.
[DESIGN-CHOICE: multi-dimensional impact scoring adapted from FMEA risk-priority
scoring and structural-propagation principles from dependency-graph research.
Artifact Stakes and threshold bands are heuristics — see Calibration Notes.]

---

## Phase 1 — Semantic Scan

Evaluate each dimension against the change request description.

### Procedure

For each of the 10 dimensions, determine:
- **Is there a direct impact?** (yes/no)
- **Impact depth** (I):
  - 0 = no impact
  - 1 = cosmetic (labels, copy, minor display)
  - 2 = logic (new conditions, validation, flow branches)
  - 3 = structural (new entities, schemas, endpoints, pages)

### Refinement pass (mandatory)

After initial scan, re-read the change request and check dimensions D4–D7
again (API, UI, Permissions, Edge Cases).
[DESIGN-CHOICE: explicit second-pass on middle dimensions guards against
systematic under-evaluation of non-first/non-last items in structured lists.]
Adjust any dimension that was initially scored 0 but deserves >= 1 on
second look.

---

## Phase 2 — Structural Propagation (Coupling Matrix)

Apply the coupling matrix to find transitive (cascade) impacts.

### Rules

1. Start from all dimensions with direct impact (I > 0 from Phase 1).
2. For each directly impacted dimension, check outgoing edges in the matrix.
3. If edge strength >= 2 AND target dimension has I = 0: mark as cascade impact.
   - Cascade I = max(1, source_I - 1) (degrades by hop)
   - Cascade C = source_C - 1 (min 1) (confidence degrades)
   - Note: at min C=1, a two-hop cascade is indistinguishable from a one-hop
     cascade by confidence alone. The scored verdict (I×C×A) still differentiates
     them via I degradation across hops.
4. Max hop depth = 2. Do NOT propagate beyond 2 hops. [CALIBRATION-NEEDED:
   the 2-hop cap is a heuristic chosen to bound transitive blast radius; a
   deeper cap may surface real far cascades, a shallower one fewer false ones —
   validate against observed missed/false cascades after 10–15 change requests.]
   **Cycle guard**: maintain a visited set of dimension IDs for each traversal
   path. If the next target is already in the visited set, do NOT propagate —
   skip that edge entirely. This prevents the D3↔D4 mutual-coupling cycle from
   overwriting a Phase 1 direct score with a phantom hop-2 cascade score.
5. If a dimension is reached by both direct and cascade: use direct (higher confidence).
6. If a dimension is reached by cascade via two different paths: use the higher score.

### Coupling Matrix (10x10)

Rows = source dimension, Columns = target dimension.
Values: 0 = independent, 1 = weak, 2 = moderate, 3 = strong (almost always co-impacted).

```
        D1   D2   D3   D4   D5   D6   D7   D8   D9   D10
D1  U   -    1    0    0    1    1    0    0    0    0
D2  J   0    -    1    1    3    0    2    0    1    1
D3  DM  0    0    -    3    0    0    1    3    1    2
D4  API 0    1    3    -    1    1    1    0    3    3
D5  UI  0    2    0    0    -    0    1    0    1    2
D6  P   0    0    0    1    1    -    1    0    1    3
D7  EC  0    0    0    0    0    0    -    0    0    1
D8  RM  0    0    1    0    0    0    1    -    0    1
D9  IS  0    0    0    1    0    0    0    0    -    1
D10 TS  0    0    0    0    0    0    0    0    0    -
```

**Key:**
- D1=Users, D2=Journey, D3=Data Model, D4=API, D5=UI
- D6=Permissions, D7=Edge Cases, D8=Rollout/Migration
- D9=Integration Surface, D10=Test Strategy

### High-coupling pairs (strength=3, rationale)

| Source → Target | Why |
|-----------------|-----|
| D2 Journey → D5 UI | New flow = new interface almost always |
| D3 Data → D4 API | Schema change = API contract change |
| D3 Data → D8 Rollout | Schema change = migration needed |
| D4 API → D3 Data | New endpoint often needs new/modified schema |
| D4 API → D9 Integration | New endpoint = new touchpoints in existing code |
| D4 API → D10 Tests | New endpoint = new test scenarios |
| D6 Perms → D10 Tests | Permission change = critical test update |

---

### Semantic Override Rule (Phase 2 only)

A **semantic override** sets a cascade dimension's I to 0 when explicit
information in the CR contradicts the computed cascade. Precedence rules:

1. **Only the executing agent may apply a semantic override** — never silently.
2. **Eligible cases**: the CR contains an explicit, unambiguous statement that
   negates the cascade (e.g. "no schema changes", "same endpoint contract").
   Absence of mention does NOT qualify as a semantic override.
3. **A=3 dimensions (D3 Data Model, D4 API, D9 Integration Surface) require
   user confirmation** before a semantic override is accepted. Present the
   computed cascade and the stated reason; receive explicit acknowledgement.
   Do NOT proceed silently.
4. **Document every override** in the state file under `## Semantic Overrides`
   (dimension, original cascade I/C, stated reason, user confirmed: yes/no).
5. If the override is disputed or unclear: **do not override** — retain the
   computed cascade value.

---

## Phase 3 — ICIAS Scoring

For each dimension with I > 0 (direct or cascade):

### Score = I x C x A

**I = Impact Depth** (from Phase 1/2):
| Value | Meaning | Examples |
|-------|---------|----------|
| 1 | Cosmetic | Label, copy, minor display change |
| 2 | Logic | New condition, validation, flow branch, field |
| 3 | Structural | New entity, endpoint, page, collection, role |

**C = Confidence** (how certain the impact is):
| Value | Meaning | When to use |
|-------|---------|-------------|
| 1 | Inferred | Cascade-only, no direct evidence |
| 2 | Probable | Logical deduction, codebase pattern suggests it |
| 3 | Certain | Explicitly stated in CR, or direct code dependency |

**A = Artifact Stakes** (pre-assigned, fixed per dimension) [CALIBRATION-NEEDED:
these bands are FMEA-borrowed heuristics; D8 Rollout/Migration at A=1 may
under-weight data-migration risk in production systems — review after 10–15
real change requests and recalibrate if D8 produces false-PATCH verdicts]:

| A=3 (High stakes) | A=2 (Medium stakes) | A=1 (Low stakes) |
|-------------------|---------------------|-------------------|
| D3 Data Model | D2 User Journey | D1 Target Users |
| D4 API | D5 UI | D7 Edge Cases |
| D9 Integration Surface | D6 Permissions | D8 Rollout/Migration |
| | D10 Test Strategy | |

> **A=1 scoring ceiling**: D1, D7, D8 have a *raw-score* ceiling of 9
> (3×3×1) → PATCH at most **by score alone**. This is a ceiling of the
> arithmetic, not a hard cap on the verdict: a structural change on an A=1
> dimension CAN still reach REDO through the **structural scope exception**
> in the Verdict thresholds section below (a user-confirmed verdict
> escalation), so REDO remains reachable for D1, D7, D8.

### Verdict thresholds

[CALIBRATION-NEEDED: the SKIP/PATCH/REDO score-band cut-points (1–2, 3–9,
10–27) are FMEA-adapted heuristics, not empirically tuned for PRD CIA; the
true cut-points that minimise false-PATCH and missed-REDO verdicts should be
revisited after 10–15 real change requests — see Calibration Notes.]

| Score Range | Verdict | Meaning |
|-------------|---------|---------|
| 0 | SKIP | No impact detected |
| 1–2 | SKIP | Negligible impact, no revision needed |
| 3–9 | PATCH | Moderate impact, surgical update to affected sections |
| 10–27 | REDO | Major impact, phase must be substantially re-executed |

> **Structural scope exception — A=1 dimensions CAN reach REDO.** By raw score
> alone, D1, D7, D8 top out at 9 (always PATCH). But a structural change
> (I=3) on one of these dimensions can still demand a full phase
> re-execution — e.g. fully re-running a rollout/migration plan (D8) or
> completely re-specifying the edge-case set (D7). When the executing agent
> judges that the scored PATCH understates the real work, it MUST:
> 1. Flag a **structural scope exception** (do not silently accept the PATCH).
> 2. Present the dimension, its score, and the reason the work is REDO-scale
>    to the user via `AskUserQuestion` (PATCH vs escalate-to-REDO).
> 3. On explicit user confirmation, **escalate the verdict to REDO** (a
>    verdict-level override, recorded alongside the score; the raw score is
>    left intact for calibration). Without confirmation, retain PATCH.
>
> This keeps REDO genuinely reachable for A=1 dimensions while preventing a
> silent over- or under-escalation. [DESIGN-CHOICE: escalation is a
> user-gated verdict override rather than an A-value bump, so the FMEA score
> stays comparable across change requests and the override is auditable.]

### Bias rule

**False negatives are worse than false positives.** When uncertain:
- Round C up, not down
- Score = 3 resolves to PATCH (not SKIP) per the threshold table above
- Prefer REDO over PATCH only when I = 3 (structural)

---

## Phase Mapping

After scoring all dimensions, map to PRD phases:

### Discovery phase impact
- ANY dimension with PATCH/REDO → Discovery needs delta update
- PATCH: update state file checklist; invoke codebase-architect on affected
  dimensions using the dimensional prompt template defined in
  `references/discovery-phase.md` Step 2 dimension loop (do not use an
  unstructured invocation).
- REDO: re-run discovery question loop for affected dims (see discovery-phase.md)

### UI Design phase impact
- D2 Journey REDO OR D5 UI REDO → UI Design REDO
- D5 UI PATCH → UI Design PATCH (update existing design)
- Otherwise → UI Design SKIP

### PRD document impact
- ANY dimension with PATCH/REDO → PRD needs update
- Map dimensions to PRD sections:

| Dimension | PRD Sections Affected |
|-----------|----------------------|
| D1 Users | 3 (Personas) |
| D2 Journey | 4 (User Stories), 7 (UI Specs) |
| D3 Data | 5 (Data Model), 12 (Dependencies) |
| D4 API | 6 (API Contract), 14 (Pipeline) |
| D5 UI | 7 (UI Specs), 8 (i18n) |
| D6 Perms | 9 (Acceptance Criteria) |
| D7 Edge Cases | 10 (Edge Cases) |
| D8 Rollout | 12 (Dependencies) |
| D9 Integration | 15 (ISA) |
| D10 Tests | 13 (Test Plan) |

### Integration Surface Analysis (ISA) — always re-scan

**Trigger**: ANY dimension receives verdict PATCH or REDO (regardless of which
dimension). The ISA re-scan is mandatory and cannot be suppressed by a SKIP
verdict on D9.

Procedure: run a delta ISA scan focused on the new requirement; merge new
touchpoints into the existing ISA table; assign new ISA-N IDs.

### Backlog Cards impact
- New verdict REDO on any dimension → evaluate whether new cards are needed
- New structural entities confirmed (I=3, REDO verdict) → new cards needed
- Changed acceptance criteria → update existing cards
- Changed dependencies → update `depends_on` fields

---

## Worked Example

**CR: "Add POST /api/v1/reservations/bulk-confirm for batch confirmation"**

Change type: Addition (new endpoint)

### Phase 1 — Semantic Scan

| Dim | Direct? | I | Rationale |
|-----|---------|---|-----------|
| D1 Users | no | 0 | Same users (merchant staff) |
| D2 Journey | yes | 2 | New batch flow alongside single confirm |
| D3 Data | no | 0 | Same reservation schema |
| D4 API | yes | 3 | New endpoint, new payload, new validation |
| D5 UI | yes | 2 | Need selection mode + bulk button |
| D6 Perms | no | 0 | Same permission (manage_reservations) |
| D7 Edge | yes | 2 | Partial failure in batch, max batch size |
| D8 Rollout | no | 0 | No migration needed |
| D9 Integration | no | 0 | (check in Phase 2) |
| D10 Tests | no | 0 | (check in Phase 2) |

### Phase 2 — Structural Propagation

Visited set for D4 traversal: {D4}

From D4 (API, I=3):
- D4→D3 (strength=3): cascade candidate. D3 I=max(1,3-1)=2, C=2.
  CR states "same reservation schema" — **semantic override requested** on
  A=3 dimension. **Requires user confirmation** (per Semantic Override Rule §3).
  Confirmed by user → override to I=0. Record in state file `## Semantic
  Overrides`: D3, cascade I=2/C=2, reason="same schema per CR", confirmed=yes.
  No cascade on D3.
- D4→D9 (strength=3): cascade. D9 I=2, C=2. Add D9 to visited.
- D4→D10 (strength=3): cascade. D10 I=2, C=2. Add D10 to visited.

From D2 (Journey, I=2), visited={D2}:
- D2→D5 (strength=3): D5 already has direct I=2 (Phase 1) → use direct.
- D2→D9 (strength=1): below threshold (strength < 2), skip.

From D5 (UI, I=2), visited={D5}:
- No outgoing strength>=2 edges.

From D7 (Edge Cases, I=2), visited={D7}:
- D7→D10 (strength=1): below threshold, skip.

### Phase 3 — ICIAS Score

| Dim | I | C | A | Score | Verdict |
|-----|---|---|---|-------|---------|
| D1 | 0 | - | 1 | 0 | SKIP |
| D2 | 2 | 3 | 2 | 12 | REDO |
| D3 | 0 | - | 3 | 0 | SKIP |
| D4 | 3 | 3 | 3 | 27 | REDO |
| D5 | 2 | 3 | 2 | 12 | REDO |
| D6 | 0 | - | 2 | 0 | SKIP |
| D7 | 2 | 3 | 1 | 6 | PATCH |
| D8 | 0 | - | 1 | 0 | SKIP |
| D9 | 2 | 2 | 3 | 12 | REDO |
| D10 | 2 | 2 | 2 | 8 | PATCH |

### Phase mapping result

| Phase | Verdict | Scope |
|-------|---------|-------|
| Discovery | PATCH | Update D2, D4, D5, D7, D9, D10 in checklist (use discovery-phase.md §Step 2 prompt) |
| UI Design | REDO | New batch selection flow |
| PRD | REDO | Sections 4, 6, 7, 10, 13, 15 |
| Backlog Cards | REDO | New cards for bulk endpoint + UI; update deps |
| ISA | RE-SCAN | Mandatory — REDO/PATCH verdicts present; delta scan for new touchpoints |

---

## Calibration Notes

These thresholds and A-value bands are FMEA-adapted heuristics, not
empirically validated for PRD CIA. All bands marked [CALIBRATION-NEEDED]
are candidates for revision. After 10–15 real change requests, review:

1. Were any SKIPs that should have been PATCHes? → Lower threshold.
2. Were any REDOs that could have been PATCHes? → Raise threshold.
3. Did the coupling matrix miss any real cascades? → Add/strengthen edges.
4. Did the coupling matrix produce false cascades? → Weaken/remove edges.
5. Were any A=1 dimensions (D1, D7, D8) under-weighted (structural scope
   exceptions raised)? → Consider raising their A value to 2.

Calibration is the responsibility of the team running `/prd-add` regularly.
Record observed false negatives and false positives in a project-owned log
(e.g. a retrospective doc or the project wiki) — impact-analysis.md itself
is a read-only reference module and cannot write to state files.
