--- name: architecture-impact description: Use when the user wants to understand the before/after architectural impact of a PR, what changed structurally, what it enables, and what risks it introduces ---

# Architecture Impact Analysis

Analyze a PR's architectural impact. Produces a decision-maker-friendly document with visual before/after diagrams, business impact framing, and honest risk assessment.

## Audience and Principles

The output targets **decision makers**: engineering leads, PMs, and stakeholders.

**Core principles:**

- **Outcomes over implementation.** Lead with what changes for users, teams, and the roadmap, not what was refactored internally. - **"So what?" test.** Every section must answer: why should a PM care about this? - **Progressive disclosure.** TL;DR first. Technical details exist for those who want them, but aren't required to understand the impact. - **Newspaper test.** If a PM read only the title, would they understand why it matters? "Enable independent deployments per framework" passes. "Extract fetch handler into core module" fails. - **One diagram = one question.** Write the question as the diagram title. If it answers multiple questions, split it. - **Honest tradeoffs.** PMs respect acknowledged risks far more than false reassurance. Always present what was rejected and why.

## Input

This skill accepts PRs only.

1. Matches GitHub URL or `#\d+` pattern -> **PR** 2. No argument -> ask: "Which PR should I analyze? Provide a PR URL or number." 3. Anything else -> "This skill analyzes PRs only. Provide a PR URL or number."

## Process Flow

```dot digraph architecture_impact { rankdir=TB; "Resolve PR" [shape=box]; "Phase 1: Analyze" [shape=box]; "Architectural?" [shape=diamond]; "Phase 2: Visualize" [shape=box]; "Phase 3: Write" [shape=box]; "Phase 4: Review" [shape=box]; "Approved?" [shape=diamond]; "Phase 5: Output" [shape=box]; "Brief note" [shape=box];

"Resolve PR" -> "Phase 1: Analyze"; "Phase 1: Analyze" -> "Architectural?"; "Architectural?" -> "Phase 2: Visualize" [label="yes"]; "Architectural?" -> "Brief note" [label="no"]; "Brief note" -> "Phase 5: Output"; "Phase 2: Visualize" -> "Phase 3: Write"; "Phase 3: Write" -> "Phase 4: Review"; "Phase 4: Review" -> "Approved?"; "Approved?" -> "Phase 3: Write" [label="revisions"]; "Approved?" -> "Phase 5: Output" [label="yes"]; } ```

**Do NOT skip phases.** If the user bundles multiple answers, accept them and skip ahead.

## Phase 1: Analyze

### Step 1 - Read the PR

Check PR size first with `gh pr view --json files,title,body,comments,reviews`.

Read: title, description, review comments (for decision rationale), commit messages, files changed.

**For the diff:** <20 files: read full diff. 20+ files: selectively read structural changes only (new/deleted/renamed files, changed interfaces, config, dependency files). Skip test files and minor edits.

### Step 2 - Read broader codebase context

Scope to packages the PR touches. Read directory tree (names only), README/architecture docs, dependency files. Goal: understand the architecture before the PR.

### Step 3 - Classify the changes

**Architectural** (changes how components relate to each other): - New modules, moved boundaries, new layers - New/removed connections between modules - Changed data flow paths or API surfaces - New design patterns introduced or replaced

**Implementation** (changes what happens inside a component): - Refactored helpers, renamed variables, added error handling, updated dependencies

### Step 4 - "So what?" framing

Before proceeding, complete this sentence:

> "We are doing [technical change] so that [business outcome], which matters because [strategic goal]."

If you cannot complete this sentence, dig deeper into the PR description and review comments until you can. This sentence becomes the spine of the entire analysis.

### Step 5 - Market impact

Go beyond internal engineering impact. Ask:

- **New users:** What user segments were blocked before that are unblocked now? Who couldn't use the product that can now? Be specific about communities, ecosystems, and their approximate size. - **New partners:** What companies, platforms, or ecosystems can the product now integrate with? What would those partnerships look like (templates, marketplace listings, co-marketing, ecosystem features)? - **Reduced adoption friction:** How does this change the adoption conversation? What did prospects have to do before vs now? (e.g., "migrate your backend" vs "add 3 lines to your existing server") - **Competitive positioning:** Does this close a gap with competitors, or open a lead?

Not every PR has market impact. Skip this step for internal-only changes. But for platform expansion, new integrations, or API surface changes, this is often the most valuable part of the analysis.

### Step 6 - Present understanding

Present in business language, not implementation language:

> **What changed:** [one sentence, outcome-focused] > **Why it matters:** [business impact] > **What it enables:** [new capabilities] > **What it costs:** [tradeoffs, risks, migration burden] > **Who this unlocks:** [new user segments, new partners] (if applicable) > > "Does this capture the intent? Anything I'm missing?"

Wait for confirmation before proceeding.

## Phase 2: Visualize

### Diagram selection

Pick the diagram type that matches the question the audience is asking:

| Audience question | Diagram type | Zoom level | |---|---|---| | "What does this system connect to?" | System context (C4 Level 1) | Highest | | "What are the major components?" | Container diagram (C4 Level 2) | High | | "How does data flow through the system?" | Sequence / flow diagram | Medium | | "What changed between before and after?" | Before/after comparison | Medium | | "What's the blast radius of this change?" | Impact radius diagram | Medium | | "What's the migration timeline?" | Phase / timeline diagram | High |

For most PRs, generate 2-3 diagrams: a **before/after comparison** (always) and one of the others based on what best communicates the change.

For **customer-facing** output, prefer: - **Fan-out diagram:** Product at center, supported targets radiating out. Communicates "one integration, many platforms." This is the headline visual. - **Before/after as value table**, not architecture diagram. Show what changed for the user (supported platforms, adoption effort, lock-in), not internal module structure. - **3-step code snippets** as visual proof: Install, Create, Mount on your server. Show the same product code with different one-line server wrappers.

### Abstraction level

Diagrams are for decision makers. Show how pieces talk to each other, not internal structure.

| Do | Don't | |---|---| | Name by role: "Runtime Core", "Express Adapter" | Name files: "fetch-handler.ts" | | Name layers: "Routing Layer", "Auth Layer" | Name functions: "matchRoute()" | | Label arrows with what flows: "SSE stream", "REST" | Label with function calls or variable names | | Use subgraphs for logical boundaries | Use subgraphs for directories | | Max 8-12 elements per diagram | Cram the entire system into one view |

**5-second test:** Show the diagram to someone for 5 seconds. Can they tell you what the system is, who uses it, and roughly what it does? If not, simplify.

### Semantic color system

Use consistently across all diagrams. Always include a legend.

``` classDef added fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#1B5E20 classDef removed fill:#FFCDD2,stroke:#C62828,stroke-width:2px,stroke-dasharray:5 5,color:#B71C1C classDef modified fill:#FFF3E0,stroke:#E65100,stroke-width:2px,color:#BF360C classDef unchanged fill:#FAFAFA,stroke:#BDBDBD,stroke-width:1px,color:#616161 classDef focus fill:#E3F2FD,stroke:#1565C0,stroke-width:3px,color:#0D47A1 ```

Always pair color with a secondary signal (dashed border for removed, thick border for added) so the diagram works for color-blind readers.

### Before/after technique

The most effective technique for communicating architectural change:

1. Draw the current state as a clean diagram 2. Duplicate it with **identical element positioning** 3. On the duplicate, make only the actual changes 4. Use the semantic colors: gray (unchanged), green (added), red+dashed (removed) 5. Place side-by-side or sequential with labels "Current" and "After this PR"

**Critical:** Keep layout identical between before and after. If you rearrange elements, the viewer wastes cognitive effort mapping old positions to new instead of understanding the change.

### Impact radius diagram (SVG)

For changes with broad blast radius, generate a concentric-circle SVG showing what's directly affected vs transitively affected. Save as a separate `.svg` file and link from the markdown.

```xml <svg viewBox="0 0 500 400" xmlns="http://www.w3.org/2000/svg"> <style> text { font-family: system-ui, sans-serif; text-anchor: middle; } .ring { fill-opacity: 0.15; stroke-width: 2; } .label { font-size: 13px; fill: #424242; } .center-label { font-size: 15px; font-weight: bold; fill: #1B5E20; } .ring-label { font-size: 11px; fill: #757575; font-style: italic; } </style> <!-- Outer ring: transitively affected --> <ellipse cx="250" cy="200" rx="230" ry="180" class="ring" fill="#FFF3E0" stroke="#E65100"/> <!-- Inner ring: directly affected --> <ellipse cx="250" cy="200" rx="150" ry="120" class="ring" fill="#E3F2FD" stroke="#1565C0"/> <!-- Center: the change --> <ellipse cx="250" cy="200" rx="70" ry="55" class="ring" fill="#C8E6C9" stroke="#2E7D32"/> <text x="250" y="205" class="center-label">Changed Component</text> <!-- Labels positioned around the rings --> <text x="250" y="45" class="ring-label">Transitively affected</text> <text x="250" y="110" class="ring-label">Directly affected</text> </svg> ```

Populate with actual component names. This diagram type has no good Mermaid equivalent, so always use SVG.

### Format and rendering

**Primary format: Mermaid** in fenced code blocks. Renders natively in VS Code, GitHub, Notion, GitLab, and most doc platforms.

**Secondary format: SVG files** for custom visuals (impact radius, custom layouts). Reference with ``.

### Writing to file

Diagrams don't render visually in the terminal. Write them to the output file (see Phase 5 for path). After writing:

> "I've written the diagrams to `<path>`. Open in a markdown previewer to see them rendered. Do they accurately represent the change?"

Wait for confirmation.

## Phase 3: Write

Write the full analysis into the output file. Pick the document structure based on the audience. If the PR has market impact (Step 5 produced new users/partners), default to the **customer-facing** structure. For internal-only changes, use the **internal** structure.

Ask the user if unclear: "This PR has market impact. Should I frame it for external stakeholders (customers, partners) or internal team?"

### Customer-facing structure

Use when the change expands who can use the product, unlocks new platforms/ecosystems, or changes the adoption story. The focus is value, market expansion, and adoption friction, not internal engineering tradeoffs.

``` # <Value-first title, no PR number> (e.g., "Run Anywhere: New Users, New Partners, No Lock-in")

## The One-Liner [One sentence: what changed and why anyone should care. Zero jargon. A developer browsing the website would nod.]

## Why This Matters [The "so what" paragraph. Frame as market expansion, not technical achievement. Use an analogy if it helps. State where the analogy breaks down.]

[Fan-out diagram: the product at center, new targets radiating out. This is the headline visual.]

## New Users This Opens Up [Table: Segment | Why they were blocked | Opportunity size. Be specific about communities and ecosystems.]

## New Partner Opportunities [Table: Partner |