design-review

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.