majiayu000 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:
- 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.
- Boundary issues: Information leakage, module boundary problems and abstraction mismatches. These compound over time and infect adjacent code.
- 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.
- Structural issues: Shallow modules, pass-through methods, classitis. These require refactoring but affect a bounded area.
- Surface issues: Naming and documentation problems. Important but lowest cost to fix and lowest risk if deferred.