# Clairvoyance > ESP for AI Coding — Agent skills on the philosophy of software design, grounded in decades of engineering experience. Good software isn't written. It's designed. Clairvoyance is a collection of software design skills for AI coding agents. Each skill is a lens grounded in decades of engineering experience to helps your agent see through complexity and write code with intent. Clairvoyance works with Claude Code, Codex, OpenCode, and any agent platform that supports skills. ## Skills - [Deep Modules](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/deep-modules/SKILL.md): 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). - [Module Boundaries](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/module-boundaries/SKILL.md): 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). - [Information Hiding](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/information-hiding/SKILL.md): 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. - [Pull Complexity Downwards](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/pull-complexity-down/SKILL.md): 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). - [General vs. Special-Purpose](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/general-vs-special/SKILL.md): 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. - [Error Design](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/error-design/SKILL.md): 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. - [Abstraction Quality](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/abstraction-quality/SKILL.md): 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). - [Naming & Obviousness](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/naming-obviousness/SKILL.md): 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. - [Comments & Documentation](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/comments-docs/SKILL.md): 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. - [Strategic Mindset](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/strategic-mindset/SKILL.md): 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. - [Design It Twice](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/design-it-twice/SKILL.md): 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. - [Code Evolution](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/code-evolution/SKILL.md): 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). - [Complexity Recognition](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/complexity-recognition/SKILL.md): 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). - [Red Flags Diagnostic](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/red-flags/SKILL.md): 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). - [Design Review Orchestrator](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/design-review/SKILL.md): 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). - [Diagnose](https://raw.githubusercontent.com/codybrom/clairvoyance/main/skills/diagnose/SKILL.md): 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). ## Which Skill Do I Need? Start with what bothers you: - Something smells but I can't pinpoint it ↳ It works, but I'd hate to maintain it → [/complexity-recognition](https://clairvoyance.fyi/skills/complexity-recognition) (+ [/red-flags](https://clairvoyance.fyi/skills/red-flags)) ↳ Every small change breaks something unexpected → see "structure" below - Every change turns into a scavenger hunt ↳ I end up editing five files for one feature ↳ The same internal details are hardcoded everywhere → [/information-hiding](https://clairvoyance.fyi/skills/information-hiding) ↳ I keep copying the same logic around → [/code-evolution](https://clairvoyance.fyi/skills/code-evolution) ↳ Things that belong together live in different places → [/module-boundaries](https://clairvoyance.fyi/skills/module-boundaries) ↳ There are layers that just pass data through → [/abstraction-quality](https://clairvoyance.fyi/skills/abstraction-quality) (+ [/deep-modules](https://clairvoyance.fyi/skills/deep-modules)) ↳ I can't tell which module owns what → [/module-boundaries](https://clairvoyance.fyi/skills/module-boundaries) - This API is painful to use ↳ Callers need too much boilerplate to use it → [/pull-complexity-down](https://clairvoyance.fyi/skills/pull-complexity-down) ↳ It only works for one specific use case → [/general-vs-special](https://clairvoyance.fyi/skills/general-vs-special) ↳ The abstraction isn't saving me any work → [/deep-modules](https://clairvoyance.fyi/skills/deep-modules) - The code is hard to read or understand ↳ I can't come up with a good name for this → [/naming-obviousness](https://clairvoyance.fyi/skills/naming-obviousness) (+ [/design-it-twice](https://clairvoyance.fyi/skills/design-it-twice)) ↳ The comments are useless or nonexistent → [/comments-docs](https://clairvoyance.fyi/skills/comments-docs) ↳ There are try/catch blocks and error paths everywhere → [/error-design](https://clairvoyance.fyi/skills/error-design) - I'm starting fresh or need a second opinion ↳ I don't know where to begin → [/diagnose](https://clairvoyance.fyi/skills/diagnose) ↳ I'm designing something from scratch → [/design-it-twice](https://clairvoyance.fyi/skills/design-it-twice) (+ [/comments-docs](https://clairvoyance.fyi/skills/comments-docs)) ↳ This was hacked together and it shows → [/strategic-mindset](https://clairvoyance.fyi/skills/strategic-mindset) (+ [/code-evolution](https://clairvoyance.fyi/skills/code-evolution)) ↳ I need to review this before it ships → [/design-review](https://clairvoyance.fyi/skills/design-review) ## Links - [GitHub](https://github.com/codybrom/clairvoyance) - [Installation](https://github.com/codybrom/clairvoyance#installation) - [Full content](https://clairvoyance.fyi/llms-full.txt) ## Source & License Created by [Cody Bromley](https://github.com/codybrom). Inspired by *A Philosophy of Software Design* by John K. Ousterhout. Licensed under the [MIT License](https://github.com/codybrom/clairvoyance/blob/main/LICENSE).