Plan Impact Analysis

Step 1: Produce the Execution Flow Diagram

Your first output is always a Mermaid diagram showing the execution flow of the plan as it moves through the codebase.

What the diagram must show:

• Entry points: where does execution begin for the new feature/change?
• Existing components touched: which current files/modules/functions are in the path?
• New components introduced: clearly distinguished from existing ones
• Decision points: branches, conditionals, or error paths in the flow
• System boundaries: where does the code cross into OS, hardware, network, external service, or another process?
• Data flow: what are the key inputs and outputs at each stage?

Diagram conventions:

- Existing components: standard boxes
- New components: boxes with a ★ prefix or (NEW) label
- System boundaries: use subgraphs
- Gaps (referenced but missing): dashed boxes labeled [GAP: name]
- Critical risk points: annotate with ⚠️

Example structure:

flowchart TD
    A[Entry Point] --> B[Existing Module X]
    B --> C[★ New Component Y]
    C --> D{Decision Point}
    D -->|path 1| E[Existing Module Z]
    D -->|path 2| F[GAP: undefined_handler]
    E --> G[[System Boundary: kernel / OS / network]]

Produce the diagram inline using a Mermaid code block so it renders immediately.

Step 2: The Risk & Gap Report

Immediately after the diagram, produce a structured report. Keep it scannable — use short bullets, not paragraphs.

2.1 — Gaps

List every gap you found (plan references something that doesn't exist in the codebase). For each gap:

• What is it?
• Where in the plan does it appear?
• Why does it matter (what breaks or stalls if this isn't resolved)?

If there are no gaps, say so explicitly.

2.2 — Risk Flags

Flag anything in the plan that warrants attention before implementation. Use your judgment about what's actually risky for this specific codebase and plan — don't apply a generic checklist. Consider (but don't limit yourself to): concurrency and shared state, performance costs, error handling, backward compatibility, security surface, resource lifetimes.

For each flag:

• What is the concern?
• Where in the codebase / plan does it appear?
• What question needs to be answered before it's safe to implement?

2.3 — Fuzzy Parts

Identify any part of the plan that is underspecified — places where the plan says something like "handle errors appropriately", "synchronize access", or "process the response" without defining the specific logic. These are not gaps (the code may exist) but the intent is unclear.

For each fuzzy part, write a specific question that would resolve it.

Step 3: The Iteration Loop

After the diagram and report, invite the user into a Q&A loop. This is not a one-shot analysis — the goal is to iterate until the user fully understands the plan AND the plan itself is tighter.

How the loop works:

User asks a question (about any part of the diagram, a risk, a gap, or a fuzzy part) → You answer it concretely, grounded in the codebase → If the answer reveals the plan needs to change, say so explicitly and propose the amendment → Track plan amendments (see below)

You ask the user a question (to resolve a gap, fuzzy part, or risk flag) → User answers → You update your understanding and reflect it in the next diagram version if warranted

When to produce an updated diagram:

Re-render the Mermaid diagram when:

• A gap is resolved (the missing component now has a definition)
• A fuzzy part is clarified and it changes the flow
• A risk flag leads to a structural change in approach
• The user explicitly asks for an updated diagram

Don't re-render for minor wording clarifications.

Tracking plan amendments:

Maintain a running ## Plan Amendments section at the end of each response during the loop. Format:

## Plan Amendments

| # | Original text | Amendment | Reason |
|---|---|---|---|
| 1 | "handle errors at the call site" | Add explicit error enum with variants X, Y, Z | Gap: no error type defined in codebase |

This gives the user a clear artifact they can fold back into the plan doc.

Step 4: Done Condition

The loop ends when the user says they're satisfied, or when all of these are true:

• No unresolved gaps
• No unanswered fuzzy-part questions
• No open risk flags that could block implementation

At that point, offer to produce one of:

1. A clean updated version of the plan with all amendments applied
2. A handoff summary for the implement-from-plan skill (if they're about to implement)
3. Both

Do not offer to write implementation code here. That is a separate step.

Hard Rules

• No implementation code. Header-style type/interface definitions are fine if they help clarify a gap or data structure, but no function bodies, no logic.
• No assumptions about missing pieces. If it's not in the codebase, it's a gap. Flag it.
• Ground every claim in the code. If you say "module X owns this responsibility," you should have read module X.
• Keep the diagram honest. Don't draw components that don't exist without labeling them as new or as gaps.