review-arch

What this skill does

# 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 code?")
- Adjust the scope based on what they see
- Reprioritize items

**Continue iterating until the operator is satisfied with the plan.** Don't rush this — architectural decisions are consequential and benefit from deliberation.

When invoked by an orchestrator, the orchestrator applies its own judgment to the iteration step: it may remove items it intends to implement inline as part of its workflow, add items it wants tracked that the agent missed in its narrow analysis, or reprioritize based on the larger project context. See [`references/autonomy.md`](../../references/autonomy.md) for the orchestrator's discretion in this kind of plan-shaping decision.

### 5. Offer to Cut Tickets

Once the plan is finalized, offer to convert the planned work into tickets. **This is the only place the skill writes to anything outside the working tree.**

**Generate a draft ticket per blueprint item.** Group related items into a single ticket if doing so makes the work cohesive (e.g., "dissolve helpers.go: distribute its 6 functions" is one ticket, not six). Each ticket includes:

- **Title** — short, action-oriented (e.g., "Dissolve helpers.go; distribute functions to domain owners").
- **Description** — the rationale from the blueprint plus the specific moves/renames involved.
- **Recommended implementation skill** — name the skill that should pick this up, with scope hint. Examples:
  - "Implementation: `/refactor` with scope `src/utils/`" (for mechanical changes within an existing module)
  - "Implementation: `/scope` first to plan dependencies, then `/implement`" (for new module creation)
  - "Implementation: `/implement-batch` with this ticket plus the related `request.go` absorption ticket" (for cross-cutting changes)
- **Acceptance criteria** — what "done" looks like for this ticket (tests still pass, specific symbols moved, specific files removed).

**Preview the full ticket set to the operator.** Show all tickets at once so the operator can see the whole plan. The operator can:

- Approve as-is
- Edit titles, descriptions, or acceptance criteria
- Remove tickets they don't want cut (decline)
- Add labels (default to no labels; offer common candidates: `refactor`, `tech-debt`, `arch`)

When invoked by an orchestrator, the dispatch is the same — the orchestrator is just another receiver of the same offer (see [`references/