git:20260722.fcfda01 to git:20260919.b55f118

---

name: design-review

argument-hint: "[file, module, or PR to review]"

allowed-tools: Read, Grep

---

# Design Review Orchestrator

When invoked with $ARGUMENTS, scope the entire review to the specified target. Read the target code first, then proceed through the phases below in order. This skill orchestrates other skills from Clairvoyance (https://clairvoyance.fyi). It works best when the full collection is installed.

This skill does not replace individual lenses. It sequences them into a diagnostic funnel that moves from broad to narrow, skipping work when early phases find nothing actionable.

## Diagnostic Funnel

### Phase 1: Complexity Triage

Apply **complexity-recognition** checks against the target.

- Identify the three symptoms: change amplification, cognitive load, unknown unknowns

- Trace any symptoms to root causes: dependencies or obscurity

- Weight findings by the complexity formula: high-traffic code first

This phase determines whether the target has measurable complexity problems. If it does, subsequent phases diagnose where.

### Phase 2: Structural Review

Apply these lenses to the target's module-level architecture:

- **module-boundaries**: Are the boundaries drawn around knowledge domains or around steps in a process?

- **deep-modules**: Does each module provide powerful functionality behind a simple interface? Check for classitis, pass-through methods and shallow wrappers.

- **abstraction-quality**: Does each layer provide a genuinely different way of thinking, or do adjacent layers duplicate the same abstraction?

Focus on the modules that Phase 1 identified as highest-complexity. If Phase 1 found nothing, scan the largest or most-connected modules.

### Phase 3: Interface Review

Apply these lenses to the interfaces exposed by the modules from Phase 2:

- **information-hiding**: Does the interface leak implementation details? Check for back-door leakage (shared knowledge not in any interface).

- **general-vs-special**: Does the interface mix general-purpose mechanisms with special-case knowledge? Check for boolean parameters serving one caller.

- **pull-complexity-down**: Are callers forced to handle complexity the module could absorb? Check for exposed edge cases, required configuration and exceptions that could be defined away.

- **error-design**: Are errors defined out of existence where possible? Check for catch-and-ignore, overexposed exceptions and error handling longer than the happy path.

### Phase 4: Surface Review

Apply these lenses to naming and documentation:

- **naming-obviousness**: Do names create precise mental images? Check the isolation test: seen without context, could the name mean almost anything?

- **comments-docs**: Do comments capture what the code cannot say (intent, rationale, constraints)? Check for comments that repeat code and implementation details contaminating interface documentation.

### Phase 5: Red Flags Sweep

Run the full **red-flags** 17-flag checklist against the target. Any flag triggered in Phases 1-4 will already be marked. This phase catches flags that earlier phases may not have surfaced (especially Process flags 15-17: No Alternatives Considered, Tactical Momentum, Catch-and-Ignore).

## Early Termination

If Phase 1 finds no measurable complexity AND Phase 5 triggers zero flags, stop. Report the target as clean. Do not force findings where none exist.

## Prioritization

Rank findings in this order:

1. **Syndrome clusters**: Multiple flags pointing to the same root cause (e.g., information leakage + conjoined methods + repetition all stemming from one misplaced boundary). These indicate systemic issues. Fixing the root cause resolves all flags in the cluster.

2. **Boundary issues**: Information leakage, module boundary problems and abstraction mismatches. These compound over time and infect adjacent code.

3. **Canary flags**: Hard to Pick Name, Hard to Describe, Non-obvious Code, No Alternatives Considered. These are the cheapest signals. Catch them and the structural flags never materialize.

4. **Structural issues**: Shallow modules, pass-through methods, classitis. These require refactoring but affect a bounded area.

5. **Surface issues**: Naming and documentation problems. Important but lowest cost to fix and lowest risk if deferred.

## Reviewing at Scale

The funnel above is written for one target reviewed in-conversation. When the target is an entire codebase, a large PR spanning many files, or the user asks for a "thorough" or "comprehensive" review, running it once per file in a single conversation burns context fast and serializes work that has no reason to be serial.

If Dynamic Workflows are available in this session (the user said "workflow," used the `ultracode` keyword, or `/effort ultracode` is set), build one instead of running the funnel manually file by file. See [references/workflow-builder.md](references/workflow-builder.md) for how to map these five phases onto a workflow script — what fans out, what needs a barrier, and where to add adversarial verification. If workflows aren't available, fall back to running the funnel per file or module in sequence, same as a single-target review.