baldart 3.41.0 → 4.0.0

package/framework/.claude/skills/prd-add/references/impact-analysis.md

@@ -1,233 +0,0 @@
-# ICIAS Impact Analysis Protocol
-
-Full protocol for Change Impact Analysis on PRD sessions.
-Based on ProReFiCIA (Etezadi et al. 2025), CodePlan (Bairi et al. 2023),
-and FMEA-adapted scoring.
-
----
-
-## 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 4-7
-again (the "middle" of the list — LLMs tend to under-evaluate items in
-the middle of lists, per "lost-in-the-middle" research). 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)
-4. Max hop depth = 2. Do NOT propagate beyond 2 hops.
-5. If a dimension is reached by both direct and cascade: use direct (higher confidence).
-
-### 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 |
-
----
-
-## 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):
-| 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 | |
-
-### Verdict thresholds
-
-| Score Range | Verdict | Meaning |
-|-------------|---------|---------|
-| 0 | SKIP | No impact detected |
-| 1–3 | SKIP | Negligible impact, no revision needed |
-| 4–9 | PATCH | Moderate impact, surgical update to affected sections |
-| 10–27 | REDO | Major impact, phase must be substantially re-executed |
-
-### Bias rule
-
-**False negatives are worse than false positives.** When uncertain:
-- Round C up, not down
-- Prefer PATCH over SKIP when on the boundary (score = 3)
-- 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, run codebase-architect on affected dims
-- REDO: re-run discovery question loop for affected dims
-
-### 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) |
-
-### Backlog Cards impact
-- New structural entities (I=3) → new cards needed
-- Changed acceptance criteria → update existing cards
-- Changed dependencies → update `depends_on` fields
-
----
-
-## Worked Example
-
-**CR: "Add POST /api/v1/merchant/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
-
-From D4 (API, I=3):
-- D4→D3 (strength=3): cascade. D3 I=max(1, 3-1)=2, C=2 → but wait,
-  CR says "same schema" → override to I=0. No cascade (semantic override).
-- D4→D9 (strength=3): cascade. D9 I=2, C=2
-- D4→D10 (strength=3): cascade. D10 I=2, C=2
-
-### 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 |
-| UI Design | REDO | New batch selection flow |
-| PRD | REDO | Sections 4, 6, 7, 10, 13, 15 |
-| Backlog Cards | PATCH | New cards for bulk endpoint + UI; update deps |
-
----
-
-## Calibration Notes
-
-These thresholds are FMEA-adapted heuristics, not empirically validated
-for PRD CIA. 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.
-
-Track calibration data in state file `## Change Requests` section.