# Architecture Impact
> 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
- Skill: `alemtuzlak/architecture-impact` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add alemtuzlak/architecture-impact`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alemtuzlak/architecture-impact/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: AlemTuzlak (https://skillmd.com/u/alemtuzlak)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alemtuzlak/architecture-impact
---
# 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
```
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 ``. 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.
```
#
(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 | What the partnership looks like.
Concrete: templates, marketplace listings, co-marketing.]
## How Adoption Works Now
[3-step pattern: Install, Create, Mount.
Show the same product code with different one-line server mounts.
The message: "Your stack doesn't change. You just add [product]."]
## Before and After
[Comparison table framed as value, not architecture:
Supported platforms, adoption requirement, lock-in, etc.
No file names, no internal module structure.]
## The Value in One Sentence
[One bold sentence that captures the market impact.
e.g., "Every developer with a JS backend is now a potential
customer, with zero migration cost."]
```
### Internal structure
Use for changes that matter to the team but don't change the external story (refactors, internal tooling, CI improvements, performance work).
```
# Architecture Impact: PR # -
**Repo:** | **Date:** | **PR:**
## TL;DR
- [What's changing, in outcome terms]
- [Why now / what triggered this]
- [What it costs: time, coordination, risk]
## Business Context
[One paragraph: what problem this solves and why it matters.
Complete the "so what" sentence from Phase 1 Step 4.]
## Before
[How the affected area was structured and what the pain points were.
Use an analogy if it helps.]
## After
[What changed and how it's structured now.
Ground the analogy.]
## What This Enables
[Concrete capabilities unlocked. Use bullets. Each bullet should
pass the newspaper test -- would a PM nod?]
## Impact Assessment
### Six Questions
| Question | Answer |
|---|---|
| **Will this break anything?** | [Honest risk + mitigation] |
| **Timeline impact?** | [What slows down, for how long] |
| **New capabilities?** | [What's possible now that wasn't] |
| **Velocity impact?** | [Short-term cost vs long-term gain] |
| **Other teams affected?** | [Who needs to do what] |
| **Reversible?** | [Rollback plan and time to execute] |
### Tradeoffs
| What we gain | What it costs |
|---|---|
| [Concrete gain] | [Concrete cost] |
## Diagrams
[Before/after comparison -- always included]
[Additional diagrams as selected in Phase 2]
[Impact radius SVG if applicable]
[Legend -- always included when using color coding]
```
### Writing rules
- **Lead with outcomes, not implementation.** The first paragraph should contain zero jargon.
- **Name by role, not by file.** "The request handler", "the Express adapter", not "fetch-handler.ts".
- **Describe how pieces talk, not what happens inside.** "All adapters now delegate to a shared core" is architectural. "The handler calls matchRoute which returns a discriminated union" is implementation.
- **Use one analogy**, then ground it in specifics. State where it breaks down.
- **Quantify where possible.** "Velocity dips ~30% for 3 weeks" beats "might slow things down."
- **Never use em-dashes** in the generated content. Use commas, colons, periods, or parentheses.
- **Short paragraphs, scannable.** No wall of text.
- **Include the baseline.** What happens if we do nothing?
## Phase 4: Review
> "The complete analysis is at ``. Open in a markdown previewer to review with rendered diagrams. Want any changes?"
Wait for approval. Apply changes by editing the file.
## Phase 5: Output
### Path resolution
Default: `docs/architecture/PR--impact.md`
Ask early (start of Phase 2): "I'll write the analysis to `docs/architecture/PR--impact.md`. Want a different location?"
If SVG diagrams were generated, place them alongside: `docs/architecture/PR--impact-radius.svg`
Print a brief terminal summary (title + one-line + path). Do NOT print the full document to terminal.
## Error Handling
- `gh` not available -> cannot proceed, inform user
- Invalid PR -> ask user to verify
- PR too large -> focus on structural changes, note what was skipped