/review-arch

name: review-arch
description: Architectural review workflow. Analyzes codebase organization via noun analysis and produces a target blueprint. Advisory only — does not implement changes. Always offers to cut tickets for the planned work; orchestrators receive the proposal and apply their own autonomy judgment to approve / edit / decline.
model: opus

Arch Review — Advisory Architectural Analysis

Analyzes codebase architecture and produces a target blueprint via noun analysis. **Advisory only.** The skill does not implement changes — it surfaces opportunities and offers to cut tickets so the work can be picked up by implementation skills. The offer goes to the operator (human or orchestrator) regardless of caller; orchestrators apply their own autonomy judgment to approve / edit / decline.

Philosophy

**Review and implementation are different concerns.** A skill that does both makes both worse — implementation pressure compromises the review, and review pressure compromises the implementation. The plugin is moving `/review-*` skills toward advisory-only over time (see the "Advisory aspiration" section of [`references/autonomy.md`](../../references/autonomy.md)); `/review-arch` is the first concrete step in that direction.

**Clarity through organization is the goal.** Every module should have a clear identity — a domain noun it owns. Functions should live where a reader expects to find them. DRY and Prune serve this organizational goal, not the other way around.

**Recommend boldly.** The analysis agent surfaces every opportunity it finds, even uncertain ones — the operator can always reject a recommendation when reviewing the plan. The skill's job is to *see*, not to *act*.

**Single workflow for everyone.** The skill's workflow is identical whether a human operator or an orchestrator (`/lead-refactor`, `/implement-project`, `/lead-project`) is at the receiving end. After the analysis, the skill presents a proposed ticket structure for the recommended work; the operator (human or orchestrator) approves, edits, or declines. Orchestrators apply their own autonomy judgment per [`references/autonomy.md`](../../references/autonomy.md) — declining items they intend to implement inline, approving items they want tracked for later.

Workflow Overview

┌─────────────────────────────────────────────────────────────────┐
│           ARCH REVIEW WORKFLOW (advisory)                       │
├─────────────────────────────────────────────────────────────────┤
│  1. Determine scope                                             │
│  2. Spawn swe-arch-reviewer agent (full analysis)               │
│     → returns dead code list + target blueprint                 │
│  3. Present analysis to operator                                │
│  4. Iterate on plan with operator                               │
│  5. Offer to cut tickets                                        │
│     ├─ Preview ticket set                                       │
│     ├─ Operator approves / edits / declines                     │
│     └─ Create approved tickets in tracker with labels           │
│  6. Completion summary                                          │
│     └─ Tickets created (or "no tickets — analysis only")        │
└─────────────────────────────────────────────────────────────────┘

Workflow Details

1. Determine Scope

**Scope:** Default is the entire codebase. If the caller specifies a path or module, respect that scope. Pass scope to the analysis agent.

2. Analyze Codebase

**Spawn fresh `swe-arch-reviewer` agent:**

The agent performs four sequential analysis steps:

1. Catalogs dead code for removal 2. Builds a domain model via noun analysis 3. Catalogs repetition patterns 4. Produces a target architecture blueprint

**Prompt the agent with:**

Perform a full architectural analysis of this codebase.
Scope: [entire codebase | user-specified scope]
Produce a comprehensive target architecture blueprint showing where
everything should live. Cover every module — existing and proposed.

The agent returns:

• A noun frequency table (the primary analytical artifact)
• A per-noun namespace evaluation
• A dead code list
• A repetition catalog (DRY candidates, resolved in the blueprint)
• A target architecture blueprint (existing modules + proposed new modules)
• Any linter/formatter issues observed
• Any behavior-altering implications worth flagging

**If the agent reports "No refactoring needed":** Workflow complete. Skip to step 6 (completion summary) with an empty findings list.

3. Present Analysis to Operator

After the analysis agent returns, present its findings to the operator (human or orchestrator). The operator needs to see the full picture before deciding what to do.

**Present three things:**

**a) Noun analysis.** Show the noun frequency table and the per-noun namespace evaluations. This is the analytical foundation — the user should understand what nouns the agent identified, how frequently they appear, and why they do or don't deserve their own namespace.

**b) Proposed changes.** Show the blueprint items — modules to change, absorb, dissolve, or rename, plus proposed new modules. For each item, include the agent's rationale. Group by category (dead code removal, renames, moves, absorptions, dissolutions, new modules).

**c) No-change items.** Show the modules the agent evaluated and explicitly decided to leave alone, with their domain justifications. This is important context — the operator may disagree and want to add items, or may spot a module the agent missed entirely.

4. Iterate on Plan with Operator

The operator has the full analysis. Give them the opportunity to shape the plan before any tickets are cut.

**The operator may want to:**

• Remove items they disagree with
• Add items the agent missed
• Modify proposed changes (e.g., "move that function to module X instead of Y")
• Ask questions about specific recommendations ("why did you flag this as dead