clairvoyance.fyi

Clairvoyance: software design skills for AI coding agents, inspired by A Philosophy of Software Design. Each tool named after a skill returns that skill's instructions. Call it when its description matches what you're doing, then follow it. Skills that link files in a references/ folder say how to load them with fetch-reference. Skills: - deep-modules: Measures module depth: whether the interface is simple relative to the implementation behind it. - module-boundaries: Evaluates where module boundaries are drawn and whether modules should be merged or split. - information-hiding: Checks for information leakage across module boundaries, including temporal decomposition and false encapsulation. - pull-complexity-down: Checks whether complexity is pushed to callers or absorbed by implementations — the direction complexity flows. - general-vs-special: Evaluates whether interfaces are appropriately general-purpose. - error-design: Reviews error handling and exception design, applying the "define errors out of existence" principle. - abstraction-quality: Evaluates whether abstractions provide a genuinely different way of thinking or are structurally shallow. - naming-obviousness: Reviews naming quality and code obviousness via the isolation test, scope-length principle, and consistency audit. - comments-docs: Reviews comment quality and documentation practices: the four comment types, comments-first workflow, and comment rot. - strategic-mindset: Assesses whether code reflects strategic or tactical thinking, including the 10-20% investment rule and tactical-tornado patterns. - design-it-twice: Generates and compares at least two fundamentally different design alternatives on concrete criteria before committing. - code-evolution: Evaluates whether changes to existing code maintain or degrade design quality. - complexity-recognition: Diagnoses whether complexity exists and where it comes from, using the three-symptom, two-root-cause framework. - red-flags: Scans code against 17 design smells (the book's 14 named Red Flags plus 3 process-stage signals) and produces a structured diagnostic report. - design-review: Orchestrates a structured design review, running the other skills as a diagnostic funnel from complexity triage to a full red-flags sweep. - diagnose: Routes a vague symptom or complaint to the most relevant Clairvoyance skill via a decision tree.