codybrom/clairvoyance Skills

Evaluates whether abstractions genuinely provide a fundamentally different way of thinking or are structurally shallow. Use when adjacent layers feel redundant, when decorator/wrapper patterns add boilerplate without depth or when an abstraction feels leaky. Not for measuring a single module's interface-to-implementation ratio (use deep-modules) or checking for information leakage across boundaries (use information-hiding).

Evaluates whether modifications to existing code maintain or degrade design quality. Use when reviewing changes to existing code (diffs, PRs, or recently modified files) to assess whether each change looks designed-in or bolted-on. Not for scanning against a checklist of design smells (use red-flags) or assessing overall design investment (use strategic-mindset).

Reviews comment quality and documentation practices. Use when the user asks to review comments or documentation, when comments just repeat the code, when something is hard to describe in a sentence, or when writing documentation before code to surface design problems. Evaluates the four comment types, comments-first workflow, and comment rot.

Diagnoses what makes code complex and why, using the three-symptom two-root-cause framework. Use when code feels harder to work with than it should but the specific problem is unclear. This skill identifies WHETHER complexity exists and WHERE it comes from. Not for scanning a checklist of known design smells (use red-flags) or evaluating a specific module's depth (use deep-modules).

Measures module depth, whether the interface is simple relative to the implementation behind it. Use when a module's interface has too many parameters or methods, when there are too many small classes each doing too little or when methods just forward calls to other methods. Not for evaluating whether adjacent layers provide different abstractions (use abstraction-quality) or deciding whether to merge/split specific modules (use module-boundaries).

Generates and compares design alternatives before committing. Use when the user asks to design something twice, before committing to any significant design. Applies to classes, modules, APIs and architectural approaches. Ensures at least two fundamentally different alternatives were considered and compared on concrete criteria before choosing.

Orchestrates a structured design review by running existing skills in a diagnostic funnel, from complexity triage through structural, interface, and surface checks to a full red-flags sweep. Use when reviewing a file, module or PR for overall design quality and you want a comprehensive, prioritized assessment rather than a single-lens check. Not for applying one specific lens (use that skill directly) or for evolutionary analysis of how code changed over time (use code-evolution).

Routes a vague symptom or complaint to the most relevant Clairvoyance skill via a decision tree. Use when someone describes a problem but doesn't know which skill to reach for. Not for running a comprehensive review (use design-review) or scanning a checklist (use red-flags).

Reviews error handling strategy and exception design. Use when the user asks to review error handling, when a module throws too many exceptions, or when callers must handle errors they shouldn't need to know about. Applies the "define errors out of existence" principle with a decision tree for exception strategies.

Evaluates whether interfaces are appropriately general-purpose. Use when the user asks to check interface generality, when a module has if-branches or parameters serving only one caller, when getters/setters expose internal representation, or when an interface is over-specialized. Checks general-purpose design, special-general mixture, and defaults.

Checks for information leakage across module boundaries. Use when the user asks to check information hiding, when modules seem to change together, when implementation details leak across boundaries, or when structure follows execution order rather than knowledge ownership. Detects temporal decomposition and false encapsulation.

Evaluates where module boundaries are drawn and whether modules should be merged or split. Use when deciding whether to combine or separate two specific modules, when two modules seem tightly coupled, or when a change to one module forces changes to another. Not for evaluating depth within a single module (use deep-modules) or quality of an abstraction layer (use abstraction-quality).

Reviews naming quality and code obviousness. Use when the user asks to check naming, when names feel vague or imprecise, when something is hard to name (a design signal, not a vocabulary problem), or when code behavior isn't obvious on first read. Applies the isolation test, scope-length principle, and consistency audit.

Checks whether complexity is pushed to callers or absorbed by implementations. Use when callers must do significant setup, handle errors the module could resolve or configure things they don't understand. This skill focuses specifically on the direction complexity flows. Not for evaluating overall module depth (use deep-modules) or checking for knowledge leakage across boundaries (use information-hiding).

Scans code against 17 named design smells and produces a structured diagnostic report. Use when reviewing a PR for design quality, evaluating unfamiliar code against a comprehensive checklist or when the user asks for a red flags scan. Not for diagnosing why code feels complex (use complexity-recognition) or evaluating whether a PR maintains design trajectory (use code-evolution).

Assesses whether code reflects strategic or tactical thinking. Use when the user asks to evaluate design investment, when code was written under time pressure, when a developer consistently produces working code that degrades the system, or when assessing whether a codebase invests in design. Checks the 10-20% investment rule and tactical tornado patterns.