# Cognitive Coverage

> >

- **Type:** Skill
- **Install:** `agentstack add skill-ryannadel-cognitive-coverage-cognitive-coverage`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ryannadel](https://agentstack.voostack.com/s/ryannadel)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ryannadel](https://github.com/ryannadel)
- **Source:** https://github.com/ryannadel/cognitive-coverage/tree/main/skills/cognitive-coverage

## Install

```sh
agentstack add skill-ryannadel-cognitive-coverage-cognitive-coverage
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Cognitive Coverage — Skill Instructions

You generate a **cognitive coverage system** — coordinated artifacts that help people build genuine understanding of projects, codebases, research corpora, or documentation they didn't create.

## Philosophy

> When AI generates code, a developer may accept it without building a mental model.
> When a team inherits a codebase, research corpus, or documentation set, they may skim without
> truly understanding. Over time this creates **cognitive debt** — the system works (or the
> knowledge exists), but the understanding and mental models are missing or flawed.
>
> Cognitive coverage closes that gap by producing structured, quiz-verified learning materials
> anchored to the actual source material.

## The Artifacts

| # | Artifact | File | Purpose |
|---|----------|------|---------|
| 1 | Teaching Guide | `cognitive-coverage/learning-guide.html` | Interactive HTML with sections, code/content snippets, mental models, level controls, quiz |
| 2 | Coverage Manifest | `cognitive-coverage/cognitive-coverage.json` | Machine-readable inventory of what needs to be understood |
| 3 | Coverage Dashboard | `cognitive-coverage/cognitive-coverage.html` | Visual status board with gap analysis and teaching guide links |
| 4 | Artifact Launcher | `cognitive-coverage/cognitive-coverage-open.html` | Lightweight landing page that links to every generated artifact |

Generate them in order: Guide → Manifest → Dashboard → Artifact Launcher. Save them in `cognitive-coverage/` by default unless the user specifies a different output directory. After verification, automatically open `cognitive-coverage/cognitive-coverage-open.html` in the user's default browser.

---

## Phase 0: Domain Detection

Before analyzing content, detect the project domain:

### Detection Rules

| Signal | Domain |
|--------|--------|
| Source code files (.ts, .py, .rs, .go, .java, .js, .rb, .cs, .cpp, etc.) | `codebase` |
| Research papers (.pdf), bibliographies (.bib), datasets (.csv, .parquet) | `research` |
| Documentation (.md, .mdx, .rst, .adoc), wiki structure, docs/ folders | `documentation` |
| Mixed signals | Ask the user or use `hybrid` |
| No clear signals (plain files, notes) | `knowledge` (general) |

### Domain Vocabulary

Each domain uses adapted terminology for the three coverage axes:

```
CODEBASE:
  files_label: "Source Files"
  concepts_label: "Concepts & Patterns"
  flows_label: "Data Flows"
  file_statuses: ["uncovered", "read", "understood"]
  concept_statuses: ["uncovered", "taught", "quiz-verified"]
  flow_statuses: ["uncovered", "traced", "verified"]

RESEARCH:
  files_label: "Papers & Sources"
  concepts_label: "Theories & Methods"
  flows_label: "Argument Chains"
  file_statuses: ["unread", "skimmed", "comprehended"]
  concept_statuses: ["unfamiliar", "introduced", "quiz-verified"]
  flow_statuses: ["unknown", "followed", "verified"]

DOCUMENTATION:
  files_label: "Documents & Pages"
  concepts_label: "Topics & Processes"
  flows_label: "Workflows & Procedures"
  file_statuses: ["unread", "browsed", "internalized"]
  concept_statuses: ["unfamiliar", "reviewed", "quiz-verified"]
  flow_statuses: ["unknown", "walked-through", "verified"]

KNOWLEDGE (general):
  files_label: "Sources"
  concepts_label: "Key Ideas"
  flows_label: "Connections & Sequences"
  file_statuses: ["unseen", "encountered", "mastered"]
  concept_statuses: ["unknown", "introduced", "quiz-verified"]
  flow_statuses: ["unknown", "traced", "verified"]
```

State the detected domain at the start of your output so the user can confirm or override.

---

## Phase 1: Deep Content Analysis

Before writing anything, you MUST thoroughly read and understand the project:

### For Codebases
1. **Discover structure**: List all files (excluding node_modules, dist, .git, vendor, build artifacts). Map the file tree.
2. **Identify the stack**: Read package.json / requirements.txt / go.mod / Cargo.toml etc.
3. **Read foundational files first**: Config, types/interfaces, data models, schemas.
4. **Read core logic next**: Business logic, algorithms, decision-making.
5. **Read integration layers**: API routes, controllers, middleware, database access.
6. **Read the UI/presentation layer** (if any).
7. **Read supporting files**: Utilities, helpers, seed data, environment config.
8. **Check for specs/docs**: README, spec files, design docs, comments.

### For Research
1. **Inventory sources**: List all papers, datasets, bibliographies, notes.
2. **Identify the field**: What domain/discipline? What's the research question?
3. **Read foundational papers first**: Seminal works, surveys, methodology papers.
4. **Read primary results**: Key findings papers, experimental results.
5. **Read supporting materials**: Datasets, statistical methods, replication notes.
6. **Map citation relationships**: What cites what? What builds on what?

### For Documentation
1. **Map the structure**: Table of contents, navigation hierarchy, cross-references.
2. **Identify scope**: What system/process/domain does this document?
3. **Read overview/intro pages first**: Architecture, getting started, core concepts.
4. **Read detailed pages**: API references, configuration, advanced topics.
5. **Read operational pages**: Troubleshooting, FAQs, runbooks.
6. **Map dependencies**: What pages assume knowledge from other pages?

**Do NOT start writing the guide until you have read every significant source.** Partial understanding produces misleading guides.

---

## Phase 1.5: Large Corpus Mode

Use **Large Corpus Mode** when a project is too large for a reliable single-pass guide. This applies to large codebases, monorepos, documentation portals, research collections, and mixed knowledge bases.

### When to switch modes

Before deep reading, estimate corpus size from the file tree:

- Total significant source count
- Directory/package/service boundaries
- Approximate line or token volume
- Number of domains, apps, packages, doc sections, papers, or workflows
- Whether one generated HTML guide would become too broad to teach well

Switch to Large Corpus Mode when the corpus appears too large to read and teach deeply in one context window, or when it naturally contains multiple bounded areas. State that you are using Large Corpus Mode and explain why.

### Large Corpus Workflow

1. **Index first** — inventory all significant sources, classify the domain, and cluster the project into high-level areas.
2. **Rank areas** — prioritize entry points, critical flows, security/data boundaries, high fan-in/fan-out modules, frequently changed sources, canonical docs, or highly referenced papers.
3. **Create modules** — break each area into focused teaching units that can be generated independently.
4. **Generate overview** — make `cognitive-coverage/learning-guide.html` the top-level map, learning path, and cross-area quiz by default.
5. **Generate focused guides** — when needed, write area modules as `learning-guides/.html` with their own snippets, mental models, quiz, and localStorage sync.
6. **Track explicit gaps** — mark uncovered areas/modules as gaps instead of pretending the first pass covered everything.

### Run Modes

If the user asks for a partial or incremental run, use one of these modes:

| Mode | Purpose |
|------|---------|
| `index` | Inventory, cluster, and prioritize only; do not generate full teaching modules |
| `overview` | Generate the top-level guide, manifest, and dashboard |
| `area:` | Generate or refresh one focused area/module |
| `refresh` | Re-read changed sources and update affected summaries, modules, concepts, and flows |
| `refresh:since-last-run` | Compare current sources to the last completed run baseline and refresh only impacted coverage items |
| `quiz-only` | Improve comprehension checks without regenerating all teaching content |

When using `refresh:since-last-run`, persist and reuse a deterministic baseline in the manifest:
- If git history is available, diff from the prior baseline commit/ref to the current ref.
- Otherwise compare `sourceHash` values (or modification timestamps when hashes are unavailable).
- Treat all domains the same way: "sources" can be code files, docs pages, papers, runbooks, or other tracked materials.
- If no valid baseline exists, do a normal `refresh`, then write a new baseline.

### Large Corpus Quality Standard

For large projects, "complete" means the first run is honest and navigable, not that every file is deeply taught. Verify that:

- Every significant source is inventoried or intentionally excluded
- Every high-level area has a description, priority, and gap status
- Critical flows are traced across area boundaries where possible
- Generated guides cover the highest-priority areas first
- Uncovered areas/modules are visible in the manifest and dashboard

---

## Phase 2: Concept Extraction

From your analysis, identify:

1. **The "Why"** — What problem does this project solve? What's the core insight or purpose?
2. **Key abstractions** — What are the 4-8 main concepts someone must understand?
3. **The critical flow** — What's the most important end-to-end behavior or argument? Trace it completely.
4. **Structure** — How is information/state organized? What are the key entities?
5. **Decision points** — Where are choices made that affect behavior or conclusions?
6. **Boundaries** — What are the guardrails, limitations, access controls, or scope limits?
7. **Configuration surface** — What can be changed vs. what is fixed?
8. **Common misconceptions** — What would someone likely get wrong?

### Learning Level Extraction

Assign every teachable concept, flow, area, module, and quiz question two independent learning levels:

- **Difficulty**: learner background required.
  - `beginner` — assumes little project/domain context; defines vocabulary and purpose.
  - `intermediate` — assumes the reader understands the main nouns and can follow mechanics.
  - `advanced` — assumes project fluency; focuses on edge cases, tradeoffs, failure modes, and extension points.
- **Depth**: amount of detail shown.
  - `overview` — shortest path to orientation and safe navigation.
  - `standard` — enough detail to reason about normal work.
  - `deep-dive` — implementation details, nuanced constraints, and second-order effects.

Difficulty and depth are orthogonal. For example, a beginner deep-dive can patiently unpack one foundational topic in detail, while an advanced overview can summarize an expert-only area quickly. Use `beginner` + `standard` as the default path unless the user requests a different audience.

---
## Phase 3: Teaching Guide Generation

Generate a single self-contained HTML file (`cognitive-coverage/learning-guide.html` by default) with no external dependencies.

### Required Sections

1. **The Big Picture** — Cast of characters / key entities / domain overview.
2. **Architecture / Structure Map** — Visual diagram (text/CSS-based) of how things relate.
3. **Core Model** — Data model, state shape, entity relationships, or conceptual framework.
4. **Core Algorithm / Decision Flow / Central Argument** — The most important behavior or reasoning chain, traced step by step.
5. **[3-6 additional concept sections]** — One per major subsystem, theory, or topic area, each with:
   - Snippets from the actual source material (with source path labels)
   - A "Mental Model" callout with an analogy
   - A "Warning/Key Insight" box for things easy to misunderstand
6. **Interactive Knowledge Quiz** — 10-20 questions testing comprehension across the generated difficulty/depth levels

### Required UI Components

#### Concept Cards
```html

  Title
  Explanation with references.

```

#### Mental Model Callouts
```html

  Mental Model: Analogy building intuition, not just knowledge.

```

#### Warning / Key Insight Boxes
```html

  Key insight: Something easy to misunderstand or with non-obvious implications.

```

#### Source Snippets with References
```html
path/to/source — contextName()
keyword name(...) {
  // explanation
}
```

For non-code domains, use `` or `` with the source path label. The key is always attributing content to its source.

#### Flow Diagrams (CSS-based, no images)
```html

  Step 1 → Description
  Step 2 → Description

```

#### Navigation Sidebar
```html

  Cognitive Map
  Section Group
  Section Title

```

#### Anchor and Navigation Integrity

The sidebar is a map of the actual guide, not a static template. Build it from the
sections you really emit in the document.

Rules:
1. Every sidebar link target (`href="#section-id"`) MUST match an actual
   `` in the same `learning-guide.html`.
2. Every major visible teaching section MUST appear in the sidebar exactly once.
   Do not include quiz cards, filter controls, banners, or internal sub-elements as
   top-level navigation entries.
3. If you rename, merge, split, or omit a section, update the sidebar label and
   anchor at the same time. Never leave placeholder or stale entries such as
   anchors copied from an earlier guide.
4. Use one canonical kebab-case section ID for each section and reuse it anywhere
   else that needs to link to that section, including manifest `guideSection`
   values and dashboard "Learn" links.
5. Before delivery, compare the set of sidebar anchors against the set of guide
   section IDs. The sets must match for all major teaching sections.

#### Learning Level Controls
```html

  Difficulty
    
      Beginner
      Intermediate
      Advanced
    
  
  Depth
    
      Overview
      Standard
      Deep-dive
    
  

```

Mark level-aware sections with attributes:
```html

  ...

```

The guide should remain useful with JavaScript disabled: default content must be visible, and filters should progressively enhance the page rather than hide everything.

```javascript
function applyLearningLevelFilters() {
  var difficulty = document.getElementById('difficulty-filter').value;
  var depth = document.getElementById('depth-filter').value;
  document.querySelectorAll('[data-difficulty][data-depth]').forEach(function(el) {
    var visible = el.dataset.difficulty === difficulty && el.dataset.depth === depth;
    var isDefault = el.dataset.difficulty === 'beginner' && el.dataset.depth === 'standard';
    el.hidden = !(visible || isDefault);
  });
}
```

### Quiz Requirements

The quiz is critical — it verifies genuine understanding, not just reading.

#### Quiz Rules
1. **10-20 questions** covering all major sections
2. **Multiple choice** (3-4 options per question)
3. **Every question maps to a specific concept** taught in the guide
4. **Explanations revealed on answer** — citing the specific source
5. **Score tracking** with visible counter and progress bar
6. **Reset button** to retake
7. **Level tags** — every question has `data-difficulty` and `data-depth`
8. **Mix question types**:
   - Structure questions (where is X defined/discussed?)
   - Logic questions (what does this function compute / what does this theory claim?)
   - Behavior questions (what happens when X occurs / what follows from Y?)
   - Boundary questions (what prevents X / what are the limits?)
   - System thinking questions (if you change X, what cascading effect?)
   - Application questions (if you needed to add/change/use X, which files/concepts/flows would
     you touch and what would you watch for?)
9. **localStorage sync** — write quiz results to shared coverage state, including difficulty/depth metadata

System thinking questions test second-order consequences. Application questions test the action a
reader would take first. Include at least one application question when the domain has concrete u

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ryannadel](https://github.com/ryannadel)
- **Source:** [ryannadel/cognitive-coverage](https://github.com/ryannadel/cognitive-coverage)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ryannadel-cognitive-coverage-cognitive-coverage
- Seller: https://agentstack.voostack.com/s/ryannadel
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.