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
AlemTuzlak · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add AlemTuzlak/skills --skill architecture-impact技能说明
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.
- Matches GitHub URL or
#\d+pattern -> PR - No argument -> ask: "Which PR should I analyze? Provide a PR URL or number."
- Anything else -> "This skill analyzes PRs only. Provide a PR URL or number."
Process Flow
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 diag |