Cognitive Coverage

Like test coverage, but for understanding.

Cognitive Coverage is a skill for AI coding agents that generates a measurement and learning system for any project — codebases, research papers, documentation wikis, or general knowledge domains. It produces coordinated artifacts that help you track, teach, verify, and quickly open genuine system understanding.

Works with any AI coding agent that supports custom instructions, including:

GitHub Copilot (as a Copilot skill)
Claude Code (as a custom command or CLAUDE.md instructions)
OpenAI Codex (as a system prompt)
Any LLM-powered agent with file access and markdown instruction support

The Problem

Technical debt is well understood. But there's a parallel form of debt that's harder to measure: cognitive debt — the gap between what a system does and what the people responsible for it actually understand.

Generative AI has accelerated this dramatically:

When a developer writes code from scratch, even messy code, the friction means they build at least a partial mental model. When an AI generates that same code, the developer may accept it without building the same understanding. At scale, this creates an accumulation of not knowing. The code works, but the mental models are missing.

Cognitive Coverage closes that gap.

What It Produces

Artifact	File	Purpose
Teaching Guide	`cognitive-coverage/learning-guide.html`	Interactive HTML with sections, source snippets, mental models, and quiz
Coverage Manifest	`cognitive-coverage/cognitive-coverage.json`	Machine-readable inventory tracking understanding across 3 axes
Coverage Dashboard	`cognitive-coverage/cognitive-coverage.html`	Visual status board with gap analysis and teaching guide links
Artifact Launcher	`cognitive-coverage/cognitive-coverage-open.html`	Landing page that links to all generated artifacts and opens automatically after generation

By default, all generated outputs are placed in a cognitive-coverage/ folder in the target project. The launcher is the entry point for opening the artifact set.

Reliable Artifact Writing

The skill includes shell-safe writing guidance so agents do not stall while creating large HTML files. In particular, agents are told not to use Bash heredocs such as python - <<'PY' in PowerShell, to avoid giant one-line shell strings, and to fall back to small deterministic chunks or short temporary writer scripts when native file-write tools are unavailable.

Large Codebases and Knowledge Bases

For large projects, Cognitive Coverage switches from a single exhaustive pass to Large Corpus Mode:

Inventory the full corpus first
Cluster sources into areas and focused learning modules
Prioritize critical flows, entry points, security/data boundaries, and highly referenced material
Generate cognitive-coverage/learning-guide.html as the overview map
Generate optional learning-guides/<module-id>.html pages for deeper modules
Keep uncovered areas visible as explicit dashboard gaps

This keeps the first run honest and useful: high-priority understanding is taught immediately, while lower-priority areas remain tracked instead of being hidden inside an oversized guide.

Three Coverage Axes

Axis	Codebase	Research	Documentation
Files	Source files	Papers & sources	Documents & pages
Concepts	Algorithms & patterns	Theories & methods	Topics & processes
Flows	Data flows	Argument chains	Workflows & procedures

Each axis has three status levels (e.g., uncovered → read → understood). Status terminology adapts automatically to the domain.

Quick Start

Option 1: GitHub Copilot

# Unix / macOS / WSL
git clone https://github.com/ryannadel/cognitive-coverage.git
cd cognitive-coverage
bash install.sh

# Windows PowerShell
git clone https://github.com/ryannadel/cognitive-coverage.git
cd cognitive-coverage
.\install.ps1

This copies the skill definition to ~/.copilot/skills/cognitive-coverage/SKILL.md.

Then open any project with Copilot and say:

"Generate cognitive coverage for this project"

Option 2: Claude Code

Claude Code has native skill support. Install as a project or personal skill:

# Project skill (this project only)
mkdir -p .claude/skills/cognitive-coverage
cp skill/SKILL.md .claude/skills/cognitive-coverage/SKILL.md

# Personal skill (all your projects)
mkdir -p ~/.claude/skills/cognitive-coverage
cp skill/SKILL.md ~/.claude/skills/cognitive-coverage/SKILL.md

Then invoke with /cognitive-coverage or just ask Claude to "generate cognitive coverage" — it will auto-detect the skill from the description.

See the Claude Code skills docs for more on skill placement and configuration.

Option 3: OpenAI Codex

Codex has native skill support via the .agents/skills/ directory:

# Project skill (this repo only)
mkdir -p .agents/skills/cognitive-coverage
cp skill/SKILL.md .agents/skills/cognitive-coverage/SKILL.md

# Personal skill (all your projects)
mkdir -p ~/.agents/skills/cognitive-coverage
cp skill/SKILL.md ~/.agents/skills/cognitive-coverage/SKILL.md

Then invoke with -coverage or let Codex auto-detect it from the description. Works in Codex CLI, IDE extension, and Codex app.

See the Codex skills docs for more on skill placement and configuration.

Option 4: Any Other Agent

The skill is just a markdown file (skill/SKILL.md) that tells an AI agent how to analyze a project and generate the artifact set. If your agent can:

Read files in a project directory
Follow markdown instructions
Write output files

...then it can run Cognitive Coverage. Copy skill/SKILL.md into whatever instruction mechanism your agent supports.

Manual Install

If you prefer not to clone, just copy skill/SKILL.md to the appropriate location for your agent:

Agent	Location
GitHub Copilot	`~/.copilot/skills/cognitive-coverage/SKILL.md`
Claude Code	`.claude/skills/cognitive-coverage/SKILL.md` (project) or `~/.claude/skills/cognitive-coverage/SKILL.md` (personal)
OpenAI Codex	`.agents/skills/cognitive-coverage/SKILL.md` (project) or `~/.agents/skills/cognitive-coverage/SKILL.md` (personal)
Other	Wherever your agent reads instruction files

MCP Integration (optional)

Cognitive Coverage also ships an optional MCP stdio server for agents that can call tools during a session. The skill still works without MCP; the server only exposes an existing cognitive-coverage.json manifest.

uv --directory /path/to/cognitive-coverage/mcp run python server.py \
  --manifest /path/to/your/project/cognitive-coverage.json

The server provides hierarchy-aware tools:

Tool	Purpose
`list_uncovered`	List files, concepts, or flows still at their first status
`list_areas`	List large-corpus areas and their modules
`get_area`	Return one area with modules and grouped files/concepts/flows
`next_learning_targets`	Suggest priority-ordered uncovered items to learn next
`get_concept`	Return a concept's description, files, quiz IDs, and status
`get_flow`	Return a flow's steps, file references, quiz IDs, and status
`coverage_summary`	Return the manifest summary and one-line synopsis
`find_by_file`	Return concepts and flows that reference a file path
`mark_status`	Update one item status and rewrite the manifest atomically

Example host config:

{
  "mcpServers": {
    "cognitive-coverage": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/cognitive-coverage/mcp",
        "run",
        "python",
        "server.py",
        "--manifest",
        "/path/to/your/project/cognitive-coverage.json"
      ]
    }
  }
}

Once installed, ask your agent:

"Use coverage_summary, then list_uncovered for concepts."

See mcp/README.md for Claude Code, Codex, and Cursor setup.

How It Works

  ┌──────────────────────┐
  │ Artifact Launcher    │
  │ cognitive-coverage   │
  │ /cognitive-coverage  │
  │      -open.html      │
  └──────────┬───────────┘
             │ links
             ▼
  ┌──────────────────────┐
  │   Teaching Guide     │──── quiz answers ────┐
  │  learning-guide.html │                      │
  └──────────┬───────────┘                      │
             │ "Learn" links                    ▼
  ┌──────────┴───────────┐              localStorage
  │  Coverage Dashboard  │◄──── reads ──────────┘
  │ cognitive-coverage   │
  │       .html          │
  └──────────┬───────────┘
             │ reads
  ┌──────────┴───────────┐
  │  Coverage Manifest   │
  │ cognitive-coverage   │
  │       .json          │
  └──────────────────────┘

Artifact Launcher opens automatically after generation and links to every output
Dashboard loads the manifest and renders coverage status
Gap report shows uncovered items with "Launch Teaching" buttons
Clicking a button opens the teaching guide at the relevant section
Answering quiz questions correctly writes results to localStorage
Returning to the dashboard syncs quiz results and upgrades coverage
You can also manually set status via buttons on each card
Export the updated manifest as JSON anytime

See docs/HOW-IT-WORKS.md for the full deep dive.

Domains

The skill auto-detects the project domain and adapts terminology:

codebase — Source code projects (TypeScript, Python, Rust, Go, Java, etc.)
research — Paper collections, literature reviews, datasets
documentation — Wikis, knowledge bases, runbooks, guides
knowledge — General-purpose (anything else)

Examples

See the examples/ directory for sample manifests:

examples/codebase/ — REST API project
examples/research/ — Transformer architecture paper review
examples/documentation/ — Platform engineering wiki

Schema

The manifest format is defined by a JSON Schema:

schemas/cognitive-coverage.schema.json

Use it to validate manifests programmatically or in CI.

Project Structure

cognitive-coverage/
├── README.md                          # This file
├── LICENSE                            # MIT
├── CONTRIBUTING.md                    # How to contribute
├── install.sh                         # Copilot installer (Unix/macOS/WSL)
├── install.ps1                        # Copilot installer (Windows)
├── skill/
│   └── SKILL.md                       # The skill instructions (works with any agent)
├── mcp/
│   ├── server.py                      # Optional MCP stdio server
│   ├── test_server.py                 # MCP smoke tests
│   └── pyproject.toml                 # MCP server dependencies
├── schemas/
│   └── cognitive-coverage.schema.json # JSON Schema for manifests
├── examples/
│   ├── codebase/                      # TypeScript REST API example
│   ├── research/                      # ML paper review example
│   ├── documentation/                 # Platform wiki example
│   ├── mcp-config-claude-code.json    # Claude Code MCP config snippet
│   └── mcp-config-codex.json          # Codex MCP config snippet
├── docs/
│   └── HOW-IT-WORKS.md               # Detailed system documentation
└── .github/
    ├── ISSUE_TEMPLATE/
    │   ├── bug_report.md
    │   └── feature_request.md
    └── pull_request_template.md

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Ideas for contributions:

New domain vocabularies (legal, medical, academic)
Improved quiz question patterns
Dashboard visualization improvements
Additional example manifests
Install scripts for other agents
Integrations with other tools

License

MIT

Built to fight cognitive debt — one concept at a time.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Cognitive Coverage

The Problem

What It Produces

Reliable Artifact Writing

Large Codebases and Knowledge Bases

Three Coverage Axes

Quick Start

Option 1: GitHub Copilot

Option 2: Claude Code

Option 3: OpenAI Codex

Option 4: Any Other Agent

Manual Install

MCP Integration (optional)

How It Works

Domains

Examples

Schema

Project Structure

Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.github		.github
docs		docs
examples		examples
mcp		mcp
schemas		schemas
skill		skill
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
install.ps1		install.ps1
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

Cognitive Coverage

The Problem

What It Produces

Reliable Artifact Writing

Large Codebases and Knowledge Bases

Three Coverage Axes

Quick Start

Option 1: GitHub Copilot

Option 2: Claude Code

Option 3: OpenAI Codex

Option 4: Any Other Agent

Manual Install

MCP Integration (optional)

How It Works

Domains

Examples

Schema

Project Structure

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages