execute-review

What this skill does

# Execute Review

Orchestrate a structured codebase review. You drive a two-phase pipeline -- scout then review -- and present the output to the user. Context discipline is critical throughout: every tool call and subagent dispatch should serve the review, nothing else.

**REQUIRED:** You should have been provided with a scope (directory, file, glob, or project root). If you have not, ask and immediately exit.

## The Pipeline

### 1. Scout the Codebase

Dispatch a Haiku-powered subagent to produce a structural inventory of the codebase within the given scope. The scout maps structure without reading file contents in detail.

```
<invoke name="Agent">
<parameter name="subagent_type">ed3d-basic-agents:haiku-general-purpose</parameter>
<parameter name="description">Scout codebase structure</parameter>
<parameter name="prompt">
You are a codebase scout. Your job is to produce a compact structural inventory of a codebase without reading full file contents. Be fast and precise.

**Scope:** [INSERT SCOPE]

Use Glob and Bash (for line counts, directory listing) to map:

1. **Languages**: which programming languages are present and their relative proportion (file count per extension)
2. **Frameworks/Libraries**: identify from config files (package.json, Cargo.toml, go.mod, requirements.txt, etc.)
3. **Directory layout**: top-level structure and what each directory appears to contain (src, lib, tests, config, scripts, docs, etc.)
4. **Entry points**: main files, index files, CLI entry points, server startup files
5. **Test locations**: where tests live (test/, __tests__/, *_test.go, *_spec.ts, etc.) and rough count
6. **Configuration**: build configs, CI/CD files, environment configs
7. **File counts**: total files by type within scope

Output a compact markdown inventory. Do NOT read file contents -- only names, paths, and metadata. Keep it under 300 words.

Format:

```

## Structural Inventory

**Languages:** Go (45 files), TypeScript (23 files), ...
**Frameworks:** Echo, React, ...
**Layout:**

- src/ -- main application code
- pkg/ -- shared packages
- ...

**Entry Points:** cmd/server/main.go, src/index.ts, ...
**Test Locations:** \*\_test.go alongside source (38 test files), src/**tests**/ (12 files)
**Config:** Makefile, docker-compose.yml, .github/workflows/ci.yml
**Total Files:** ~150 within scope

```
</parameter>
</invoke>
```

When the scout returns, print the structural inventory to the user so they can see what was found.

### 2. Select Files to Review

Using the structural inventory, select a representative sample of files to review. The goal is to cover the most important code without exceeding what a single reviewer agent can handle effectively.

**Selection priorities (in order):**

1. **Entry points** -- main files, server startup, CLI entry points. These reveal the application's shape.
2. **Core business logic** -- the modules that do the actual work, not glue or boilerplate.
3. **Shared utilities/packages** -- code that many other files depend on. Problems here cascade.
4. **Configuration and infrastructure** -- build configs, CI, Docker. These shape reliability.
5. **Tests** -- a sample of test files, especially for core modules. Test quality reveals code quality.
6. **API boundaries** -- route definitions, handler files, API schemas. Trust boundary code.

**Selection constraints:**

- Aim for 15-30 files for a single-pass review. Fewer for small codebases, more only if fan-out is used.
- Prefer depth over breadth -- it's better to thoroughly review 15 files than to skim 40.
- If the scope is a single file or small directory, review everything in it.
- Skip generated files, vendored dependencies, lock files, and binary assets.

Use Glob and Read (first few lines only, to assess relevance) to make your selections. List the selected files.

### 3. Decide: Single Pass or Fan-out

Estimate whether the selected files fit in a single reviewer's context:

- **Single pass** (default): 30 or fewer files, codebase is cohesive (one primary language/framework). Dispatch one reviewer.
- **Fan-out**: More than 30 files after sampling, OR the codebase has clearly separate modules (e.g., frontend + backend, multiple microservices). Partition files by module/directory and dispatch multiple reviewers in parallel.

**Fan-out heuristic:** Be conservative. If in doubt, fan out. It's better to dispatch two reviewers with clean context than one reviewer with truncated context.

If fanning out, partition files into groups where each group:

- Contains files from the same module/directory
- Has its own entry points and tests where possible
- Gets a copy of the structural inventory for orientation

### 4. Dispatch Reviewer(s)

#### Single Pass

Dispatch the `blank-slate-review:codebase-reviewer` agent with the structural inventory and file list.

```
<invoke name="Agent">
<parameter name="subagent_type">blank-slate-review:codebase-reviewer</parameter>
<parameter name="description">Review codebase: [scope summary]</parameter>
<parameter name="prompt">
## Structural Inventory

[PASTE SCOUT INVENTORY HERE]

## Files to Review

[LIST ALL SELECTED FILE PATHS, ONE PER LINE]

## Scope

[SCOPE DESCRIPTION]

Read every listed file and produce your review following the output contract in your instructions.
</parameter>
</invoke>
```

#### Fan-out

Dispatch multiple `blank-slate-review:codebase-reviewer` agents in parallel, one per module partition. Each gets the full structural inventory (for orientation) but only its partition's files.

```
<invoke name="Agent">
<parameter name="subagent_type">blank-slate-review:codebase-reviewer</parameter>
<parameter name="description">Review module: [module name]</parameter>
<parameter name="prompt">
## Structural Inventory

[PASTE SCOUT INVENTORY HERE]

## Files to Review

[LIST THIS PARTITION'S FILE PATHS ONLY]

## Scope

This is a partitioned review. You are reviewing the [module name] module as part of a larger codebase review. Focus on your assigned files.

Read every listed file and produce your review following the output contract in your instructions.
</parameter>
</invoke>
```

When all reviewers return, merge the results:

1. Concatenate findings from all reviewers
2. Re-number finding IDs sequentially (C1, C2, ..., H1, H2, ..., etc.)
3. Deduplicate: if two reviewers flagged the same file:line with the same issue, keep one
4. Merge remediation themes: combine overlapping themes from different reviewers, update finding ID references
5. Recalculate metrics

### 5. Present Output

Print the complete review to stdout. Use the exact output contract format from the reviewer agent. If results were merged from fan-out, the merged output should be seamless -- the user should not need to know how many reviewers were dispatched.

After printing the review, offer to write the findings to a file:

```
<invoke name="ToolSearch">
<parameter name="query">select:AskUserQuestion</parameter>
<parameter name="max_results">1</parameter>
</invoke>
```

Then ask:

```
Would you like me to write these findings to a file?
- Yes, write to [suggest a path like docs/review-YYYY-MM-DD.md or review.md]
- No, stdout is fine
```

If the user says yes, write the review output to the specified file. Do not commit it -- let the user decide.

## Context Discipline

This skill is designed around context cleanliness. Follow these rules:

- **No extraneous tool calls.** Every Glob, Read, Grep, or Bash call should directly serve the scout or sampling phases. Do not explore out of curiosity.
- **Be smart about tool use.** Use tools intelligently. Use tools like ast-grep (`sg`) to surgically and thoroughly work your way through the codebase, use treesitter or LSPs if appropriate. For heavyweight tools spin out a subagent to prevent from polluting main context.
- **No commentary between phases.** Move from scout to sampling to dispatch without narrating your thought process at length. Brief status updates only.
- **No redundant reads.** If the scout already told y