Cognitive Coverage

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

1. Interactive Knowledge Quiz — 10-20 questions testing comprehension across the generated difficulty/depth levels

Required UI Components

Concept Cards

  Title
  Explanation with references.

Mental Model Callouts

  Mental Model: Analogy building intuition, not just knowledge.

Warning / Key Insight Boxes

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

Source Snippets with References

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)

  Step 1 → Description
  Step 2 → Description

Navigation Sidebar

  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`.

1. 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.

1. 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.

1. 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.

1. 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

  Difficulty
    
      Beginner
      Intermediate
      Advanced
    
  
  Depth
    
      Overview
      Standard
      Deep-dive
    
  

Mark level-aware sections with attributes:

  ...

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

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?)

1. 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
• Source: ryannadel/cognitive-coverage
• License: MIT

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