Skip to content

vt-d-pd-analyze-changes

Analyze the impact of new information on the design workflow. Determines which artifacts are affected and recommends which phase to return to for iteration. Also maps pd-3 decision-log entries (SPEC-135) to the PRD sections they touch, emitting an annotate-only PRD touch-map.

Plugin: vt-product-dev
Category: Product Design Workflow
Command: /vt-d-pd-analyze-changes

Product Design: Analyze Changes

Analyze pending inbox items and determine their impact on the current design state.

Workflow Position

ITERATIVE DESIGN LOOP:

   New Input → /vt-d-pd-inbox-scan → [ /vt-d-pd-analyze-changes ] → /vt-d-pd-route-decision
                                      ▲ YOU ARE HERE

Invocation

/vt-d-pd-analyze-changes                  # Analyze all pending items
/vt-d-pd-analyze-changes --item FILE      # Analyze specific item

What This Skill Does

  1. Loads pending items from .design-state.yaml
  2. Reads and analyzes each item's content
  3. Applies the impact matrix to determine affected artifacts
  4. Aggregates impacts across multiple items
  5. Generates impact report with routing recommendations

Execution Instructions

Step 0: Prerequisites

Ensure /vt-d-pd-inbox-scan has been run first: 

# Check for pending items
Read: .design-state.yaml
# Look at inbox.pending_items where analyzed: false

If no pending items, report: 

No pending items to analyze.
Run /vt-d-pd-inbox-scan first to detect new inputs.

Step 1: Load Pending Items

From .design-state.yaml: 

inbox:
  pending_items:
    - file: "00-Inbox/usability-test-results.pdf"
      type: "usability_test"
      urgency: "HIGH"
      analyzed: false

Filter to items where analyzed: false

Step 2: For Each Item, Analyze Content

2a: Read Document

# For PDF files
Read: 00-Inbox/{filename}

# For Markdown files
Read: 00-Inbox/{filename}

# For other formats, extract what we can

2b: Extract Key Information

For each item, identify:

Field Description
Summary 1-2 sentence description of content
Findings Specific feedback points or discoveries
Severity critical, major, minor
Affected Areas personas, features, ui, flow, technical, scope

Severity Guidelines: - Critical: Blocks release, safety/compliance issue, fundamental flaw - Major: Significant usability problem, missing feature, major scope change - Minor: Polish item, minor confusion, nice-to-have suggestion

Affected Areas Keywords: - personas: user types, target audience, use cases - features: functionality, capabilities, requirements - ui: visual design, layout, components, styling - flow: user journey, navigation, steps, process - technical: performance, security, integration, data - scope: new features, removed features, timeline, priorities

Step 3: Apply Impact Matrix

Reference: ../pd-inbox-scan/references/impact-matrix.md

Change Type PRD Impact Prototype Impact specs Impact Return Phase
usability_test (critical) None HIGH None pd-3-prototype
usability_test (major) None MEDIUM None pd-3-prototype
usability_test (minor) None LOW None Continue pd-4
stakeholder_feedback (scope) HIGH HIGH HIGH pd-2-prd
stakeholder_feedback (ui) LOW HIGH LOW pd-3-prototype
stakeholder_feedback (flow) MEDIUM HIGH MEDIUM pd-3-prototype
user_research (invalidating) HIGH HIGH HIGH pd-1-research
user_research (supplementary) MEDIUM MEDIUM LOW pd-2-prd
tech_constraint (breaking) HIGH HIGH HIGH pd-2-prd
tech_constraint (limiting) MEDIUM MEDIUM MEDIUM pd-3-prototype
scope_change (addition) HIGH MEDIUM HIGH pd-2-prd
scope_change (removal) HIGH MEDIUM HIGH pd-2-prd
market_intel (critical) MEDIUM LOW LOW pd-1-research
market_intel (informational) LOW None None Continue
bug_report (prototype) None HIGH None pd-3-prototype
design_update None HIGH None pd-3-prototype

Step 4: Generate Item Analysis

For each pending item:

─────────────────────────────────────────────────────────────────
Item {n}: {filename}
─────────────────────────────────────────────────────────────────
Type: {type}
Severity: {CRITICAL | MAJOR | MINOR}
Summary: {1-2 sentence summary}

Findings:
• {finding 1}
• {finding 2}
• {finding 3}

Affected Areas: {personas | features | ui | flow | technical | scope}

Impact Assessment:
• PRD: {HIGH | MEDIUM | LOW | None} - {explanation}
• Prototype: {HIGH | MEDIUM | LOW | None} - {explanation}
• specs: {HIGH | MEDIUM | LOW | None} - {explanation}

Recommended Action: Return to {phase} | Continue current phase
─────────────────────────────────────────────────────────────────

Step 5: Aggregate Multiple Impacts

When multiple items have different recommendations:

Aggregation Rules: 1. The earliest phase wins (pd-1 < pd-2 < pd-3 < pd-4 < continue) 2. Higher severity items take precedence 3. Scope changes always require PRD review

Example: - Item 1: Return to pd-3-prototype (UI fix) - Item 2: Return to pd-2-prd (scope change) - Aggregated: Return to pd-2-prd (earlier phase, will cascade to pd-3)

Step 6: Generate Impact Report

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Product Design: Impact Analysis Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Current State: {phase} (Iteration {n})
Items Analyzed: {count}

{For each item, include full analysis from Step 4}

AGGREGATED RECOMMENDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

{Based on aggregation:}

Options:

1. [RECOMMENDED] {Primary recommendation}
   - {Description of what this entails}
   - Affects: {artifacts}
   - Estimated scope: {Full iteration | Partial rework | Minor fixes}

2. {Alternative option if applicable}
   - {Description}
   - Trade-off: {what you give up}

3. {Another alternative}
   - {Description}
   - Trade-off: {what you give up}

4. Continue current phase
   - Defer items to backlog
   - Document as known limitations
   - Proceed to next phase

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEXT STEP: /vt-d-pd-route-decision to select and execute option
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 7: Update State File

Mark items as analyzed:

inbox:
  pending_items:
    - file: "00-Inbox/{filename}"
      analyzed: true
      analysis:
        severity: "major"
        affected_areas: ["ui", "flow"]
        recommended_phase: "pd-3-prototype"

PRD Touch-Map (SPEC-154)

An additive, annotate-only second capability. Alongside the inbox pending_items analysis above (unchanged), this maps pd-3 prototype decisions to the PRD sections they touch, so the spec-author can update the PRD before it silently drifts out of sync with the built prototype. It is advisory: it reports and never rewrites PRD.md.

Scope note: this Wave surfaces which decisions touch which PRD sections (FR-1, FR-2). Detecting whether a decision contradicts the PRD (FR-3) is a separate, gated increment — see Deferred: contradiction detection below. Do not emit an assertive "contradicts" verdict here.

Step T1: Decision-log input source (FR-1)

In addition to the inbox pending_items (Step 1), auto-discover the pd-3 decision-log:

  1. Auto-discover decision records under docs/decisions/*.md whose YAML frontmatter has pd-phase: 3 (the SPEC-135 prototype-iteration records). No extra author step is required — this mirrors how Step 1 loads pending_items from the active spec's context.
  2. For each discovered record, parse its rationale (the distilled why) and its linked-files (the code paths the iteration touched). These are the only fields the touch-map reads; a record carries no PRD-section field, so section mapping is a new advisory step (Step T2), not a lookup.
  3. --item FILE remains available as a manual override to point at a single record explicitly, but auto-discovery is the primary, zero-friction path.

If no pd-phase: 3 records are found, skip the touch-map cleanly (nothing to map) and continue with the ordinary inbox analysis — the two input sources are independent.

Step T2: Advisory PRD touch-map (FR-2)

Read the PRD (auto-discover 03-PRD/PRD.md; on absence see EC-1 in Step T4). Collect its section headings (##/### lines). Then, for each discovered decision, decide which PRD section(s) it touches:

  1. Match the decision's rationale prose and its linked-files paths against the PRD headings — a decision touches a section when its rationale or a linked file names or clearly anchors that heading (a feature name, component, or requirement the heading owns).
  2. Over-report guard: list a section for a decision only when the decision actually names/anchors that heading. If a decision anchors nothing in the PRD, it contributes nothing to the map. This matching is advisory — it is a heading-name match on prose, not a reuse of the Step 3 change-type impact matrix (which keys change types to coarse severity, not decision→section).
  3. Emit the aggregate as: "N decisions touch PRD sections X, Y, Z", followed by a per-decision breakdown (DEC-NNN → §Heading with a one-line reason drawn from its rationale).

Step T3: Annotate-only emission to PRD-TOUCHMAP.md

The touch-map is surfaced, never applied. Write (or append) the report as a ## PRD Touch-Map (SPEC-154) block to a distinct advisory file 03-PRD/PRD-TOUCHMAP.md, wrapped in the provenance marker so nothing downstream mistakes it for a real requirement change:

<!-- SPEC-154 touch-map: advisory, not a PRD change -->
## PRD Touch-Map (SPEC-154)
N decisions touch PRD sections X, Y, Z.

- DEC-012 → §Search filters — rationale swaps the facet component
- DEC-013 → §Onboarding — rationale changes the first-run step order
<!-- /SPEC-154 touch-map -->

Consumed-surface guard (annotate-only NFR): never write 03-PRD/PRD.md and never write 03-PRD/PRD-DELTA.md. PRD-DELTA.md is a consumed surface — pd-pid reads it and the pd-3/pd-4 hooks append genuine requirement changes there for later incorporation; writing an advisory report into it would let pd-pid ingest it as a real change. The touch-map therefore lands only on PRD-TOUCHMAP.md, which has zero consumers. The spec-author reads it and decides whether to update the PRD by hand — the mechanism reports and asks, it does not mutate.

Step T4: Edge cases

  • EC-1 — No PRD present. If 03-PRD/PRD.md cannot be found, report "no PRD to compare against" and exit the touch-map cleanly (not an error). Do not create a PRD, and do not write PRD-TOUCHMAP.md.
  • EC-2 — Decisions touch no PRD section. If discovered decisions anchor no PRD heading, report "no PRD impact detected" — a clean, honest result, not an error. Writing an empty ## PRD Touch-Map (SPEC-154) block (N = 0) is acceptable.
  • EC-3 — Contradiction the author chooses to keep. The author may read the map, judge a touched section a deliberate change, and keep the decision. Record that decision-wins outcome (e.g. a note in the touch-map or the decision record); never force a PRD edit.

Empty map is not a guarantee. "No PRD impact detected" (EC-2) means this advisory heading-match found nothing — it does not certify that the prototype and PRD agree. The touch-map is a surfacing aid, not a proof of consistency.

Deferred: contradiction detection (FR-3, gated — NOT active)

This Wave surfaces which decisions touch the PRD. It deliberately does not decide whether a decision contradicts the PRD. Detecting contradiction is a gated future increment, not shipped here, because "touch" (a heading-name match) and "contradict" (a semantic judgement) are not equally tractable and contradiction has a real false-positive cost.

When it is eventually built, it must obey two constraints:

  1. Advisory framing, never assertive. Prompt the author with "potential conflict with PRD section X — confirm?" via AskUserQuestion. Never assert a definite contradiction and never auto-edit the PRD — the human stays the arbiter (EC-3). Wave 1 ships no such prompt.
  2. Calibration gate as a hard precondition. Activation requires passing a heuristic-calibration task first — a real decision-log corpus of 5–10 entries plus a false-positive budget — per docs/solutions/patterns/heuristic-calibration-gate.md (SPEC-127). That corpus/test belongs to the future FR-3 increment, not this spec.

Severity Decision Tree

                    ┌─────────────────────────────┐
                    │   Analyze Item Content      │
                    └──────────────┬──────────────┘
                                   │
              ┌────────────────────┼────────────────────┐
              │                    │                    │
              ▼                    ▼                    ▼
    ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
    │ Safety/Legal/   │  │ Core Journey    │  │ Polish/Minor    │
    │ Compliance      │  │ Blocked         │  │ Friction        │
    │                 │  │                 │  │                 │
    │ = CRITICAL      │  │ = MAJOR         │  │ = MINOR         │
    └─────────────────┘  └─────────────────┘  └─────────────────┘

Phase Decision Tree

                    ┌─────────────────────────────┐
                    │   Determine Return Phase    │
                    └──────────────┬──────────────┘
                                   │
          ┌────────────────────────┼────────────────────────┐
          │                        │                        │
          ▼                        ▼                        ▼
┌───────────────────┐   ┌───────────────────┐   ┌───────────────────┐
│ Requirements/     │   │ UI/UX/Visual      │   │ Minor/Polish      │
│ Scope Changed?    │   │ Changes?          │   │ Items Only?       │
│                   │   │                   │   │                   │
│ → pd-2-prd        │   │ → pd-3-prototype  │   │ → Continue        │
└───────────────────┘   └───────────────────┘   └───────────────────┘
          │
          │ User research
          │ invalidated?
          │
          ▼
┌───────────────────┐
│ → pd-1-research   │
└───────────────────┘
  • /vt-d-pd-inbox-scan - Detect new items (run first)
  • /vt-d-pd-route-decision - Execute the routing decision
  • /vt-d-pd-capture-decisions - Produces the pd-3 decision-log records (SPEC-135) read by the PRD Touch-Map
  • ../pd-inbox-scan/references/impact-matrix.md - Full impact classification rules