Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

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 review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add AlemTuzlak/skills --skill architecture-impact

About this skill


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

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 questionDiagram typeZoom 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 diagramMedium
"What changed between before and after?"Before/after comparisonMedium
"What's the blast radius of this change?"Impact radius diagramMedium
"What's the migration timeline?"Phase / timeline diag
Read the complete source ↗