Clairvoyance
ESP for AI Coding
Good software isn't written. It's designed.
Open your agent's third eye and see what it's been missing.
Extrasensory Perspective
Your agent already knows how to code. Teach it how to sense. Battle-tested philosophy on software design, grounded in decades of engineering experience.
Structure
- Deep Modules
- Module Boundaries
- Information Hiding
- Pull Complexity Down
Abstraction
- General Vs Special
- Error Design
- Abstraction Quality
Clarity
- Naming Obviousness
- Comments Docs
Process
- Strategic Mindset
- Design It Twice
- Code Evolution
- Complexity Recognition
Diagnostic
- Red Flags
- Design Review
- Diagnose
Read the Tea Leaves
Complexity hides all over your code. Each skill teaches your AI assistant exactly where to look.
Browse all skills or take the quiz →Deep Modules
Measures module depth: whether the interface is simple relative to the implementation behind it.
Read →Module Boundaries
Evaluates where module boundaries are drawn and whether modules should be merged or split.
Read →Information Hiding
Checks for information leakage across module boundaries, including temporal decomposition and false encapsulation.
Read →Pull Complexity Downwards
Checks whether complexity is pushed to callers or absorbed by implementations — the direction complexity flows.
Read →General vs. Special-Purpose
Evaluates whether interfaces are appropriately general-purpose.
Read →Error Design
Reviews error handling and exception design, applying the "define errors out of existence" principle.
Read →Abstraction Quality
Evaluates whether abstractions provide a genuinely different way of thinking or are structurally shallow.
Read →Naming & Obviousness
Reviews naming quality and code obviousness via the isolation test, scope-length principle, and consistency audit.
Read →Comments & Documentation
Reviews comment quality and documentation practices: the four comment types, comments-first workflow, and comment rot.
Read →Strategic Mindset
Assesses whether code reflects strategic or tactical thinking, including the 10-20% investment rule and tactical-tornado patterns.
Read →Design It Twice
Generates and compares at least two fundamentally different design alternatives on concrete criteria before committing.
Read →Code Evolution
Evaluates whether changes to existing code maintain or degrade design quality.
Read →Complexity Recognition
Diagnoses whether complexity exists and where it comes from, using the three-symptom, two-root-cause framework.
Read →Red Flags Diagnostic
Scans code against 17 design smells (the book's 14 named Red Flags plus 3 process-stage signals) and produces a structured diagnostic report.
Read →Design Review Orchestrator
Orchestrates a structured design review, running the other skills as a diagnostic funnel from complexity triage to a full red-flags sweep.
Read →Diagnose
Routes a vague symptom or complaint to the most relevant Clairvoyance skill via a decision tree.
Read →See It in Action
Check out how Clairvoyance skills activate in real coding sessions. Your agent sees the design problem, applies the right principle and rewrites with intent.
See through complexity
The principles behind Clairvoyance are inspired by the teachings of John Ousterhout and his book A Philosophy of Software Design. If you haven't read it, you really should.
Star on GitHub