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.