[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81050":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":12,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},81050,"cognitive-coverage","ryannadel\u002Fcognitive-coverage","ryannadel","A coding agent skill that helps measure and close the understanding gap in any codebase, research corpus, or documentation set.",null,"Python",34,6,28,1,0,4,5,12,53.64,"MIT License",false,"main",true,[],"2026-06-12 04:01:31","# Cognitive Coverage\n\n**Like test coverage, but for understanding.**\n\nCognitive 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.\n\nWorks with any AI coding agent that supports custom instructions, including:\n- **GitHub Copilot** (as a Copilot skill)\n- **Claude Code** (as a custom command or CLAUDE.md instructions)\n- **OpenAI Codex** (as a system prompt)\n- **Any LLM-powered agent** with file access and markdown instruction support\n\n## The Problem\n\nTechnical 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.\n\nGenerative AI has accelerated this dramatically:\n\n> *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.*\n\nCognitive Coverage closes that gap.\n\n## What It Produces\n\n| Artifact | File | Purpose |\n|----------|------|---------|\n| **Teaching Guide** | `cognitive-coverage\u002Flearning-guide.html` | Interactive HTML with sections, source snippets, mental models, level controls, and quiz |\n| **Coverage Manifest** | `cognitive-coverage\u002Fcognitive-coverage.json` | Machine-readable inventory tracking understanding across 3 axes |\n| **Coverage Dashboard** | `cognitive-coverage\u002Fcognitive-coverage.html` | Visual status board with gap analysis and teaching guide links |\n| **Artifact Launcher** | `cognitive-coverage\u002Fcognitive-coverage-open.html` | Landing page that links to all generated artifacts and opens automatically after generation |\n\nBy default, all generated outputs are placed in a `cognitive-coverage\u002F` folder in the target project. The launcher is the entry point for opening the artifact set.\n\n### Reliable Artifact Writing\n\nThe 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 - \u003C\u003C'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.\n\n### Large Codebases and Knowledge Bases\n\nFor large projects, Cognitive Coverage switches from a single exhaustive pass to **Large Corpus Mode**:\n\n1. Inventory the full corpus first\n2. Cluster sources into areas and focused learning modules\n3. Prioritize critical flows, entry points, security\u002Fdata boundaries, and highly referenced material\n4. Generate `cognitive-coverage\u002Flearning-guide.html` as the overview map\n5. Generate optional `learning-guides\u002F\u003Cmodule-id>.html` pages for deeper modules\n6. Keep uncovered areas visible as explicit dashboard gaps\n\nThis 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.\n\n### Three Coverage Axes\n\n| Axis | Codebase | Research | Documentation |\n|------|----------|----------|---------------|\n| **Files** | Source files | Papers & sources | Documents & pages |\n| **Concepts** | Algorithms & patterns | Theories & methods | Topics & processes |\n| **Flows** | Data flows | Argument chains | Workflows & procedures |\n\nEach axis has three status levels (e.g., `uncovered → read → understood`). Status terminology adapts automatically to the domain.\n\n### Learning Levels\n\nGenerated materials can adapt to a 3x3 learning model:\n\n| Axis | Levels | Controls |\n|------|--------|----------|\n| **Difficulty** | `beginner`, `intermediate`, `advanced` | Learner background and assumed context |\n| **Depth** | `overview`, `standard`, `deep-dive` | Amount of detail shown in the guide and quiz |\n\nThe manifest stores optional level metadata on teachable items and quiz mappings. Guides use it for progressive disclosure, dashboards use it for gap filters and level badges, and MCP tools can return level-aware next learning targets.\n\n## Quick Start\n\n### Install with `npx skills`\n\n```bash\n# OpenAI Codex\nnpx skills add ryannadel\u002Fcognitive-coverage --skill cognitive-coverage -g -a codex\n\n# GitHub Copilot\nnpx skills add ryannadel\u002Fcognitive-coverage --skill cognitive-coverage -g -a github-copilot\n\n# Claude Code\nnpx skills add ryannadel\u002Fcognitive-coverage --skill cognitive-coverage -g -a claude-code\n```\n\nUse `-g` for a user-level install, or omit it to install into the current project. Add `-y` to skip confirmation prompts.\n\n### Install with `gh skill`\n\n```bash\n# OpenAI Codex\ngh skill install ryannadel\u002Fcognitive-coverage cognitive-coverage --agent codex --scope user\n\n# GitHub Copilot\ngh skill install ryannadel\u002Fcognitive-coverage cognitive-coverage --agent github-copilot --scope user\n\n# Claude Code\ngh skill install ryannadel\u002Fcognitive-coverage cognitive-coverage --agent claude-code --scope user\n```\n\nUse `--scope user` for a user-level install, or `--scope project` to install into the current project.\n\nThen open any project with your agent and say:\n\n> \"Generate cognitive coverage for this project\"\n\n### Update the Skill\n\n```bash\n# If installed with npx skills\nnpx skills update cognitive-coverage -g -y\n\n# If installed with gh skill\ngh skill update cognitive-coverage\n```\n\nIf you installed with `npx skills` into project scope, omit `-g` when updating.\n\nFor unsupported agents, use `skills\u002Fcognitive-coverage\u002FSKILL.md` as the source skill file.\n\n## MCP Integration (optional)\n\nCognitive 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.\n\n```bash\nuv --directory \u002Fpath\u002Fto\u002Fcognitive-coverage\u002Fmcp run python server.py \\\n  --manifest \u002Fpath\u002Fto\u002Fyour\u002Fproject\u002Fcognitive-coverage.json\n```\n\nThe server provides hierarchy-aware tools:\n\n| Tool | Purpose |\n|------|---------|\n| `list_uncovered` | List files, concepts, or flows still at their first status |\n| `list_areas` | List large-corpus areas and their modules |\n| `get_area` | Return one area with modules and grouped files\u002Fconcepts\u002Fflows |\n| `next_learning_targets` | Suggest priority-ordered uncovered items to learn next, optionally filtered by difficulty\u002Fdepth |\n| `get_concept` | Return a concept's description, files, quiz IDs, and status |\n| `get_flow` | Return a flow's steps, file references, quiz IDs, and status |\n| `coverage_summary` | Return the manifest summary and one-line synopsis |\n| `find_by_file` | Return concepts and flows that reference a file path |\n| `mark_status` | Update one item status and rewrite the manifest atomically |\n\nExample host config:\n\n```json\n{\n  \"mcpServers\": {\n    \"cognitive-coverage\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"\u002Fpath\u002Fto\u002Fcognitive-coverage\u002Fmcp\",\n        \"run\",\n        \"python\",\n        \"server.py\",\n        \"--manifest\",\n        \"\u002Fpath\u002Fto\u002Fyour\u002Fproject\u002Fcognitive-coverage.json\"\n      ]\n    }\n  }\n}\n```\n\nOnce installed, ask your agent:\n\n> \"Use `coverage_summary`, then `list_uncovered` for concepts.\"\n\nSee [mcp\u002FREADME.md](mcp\u002FREADME.md) for Claude Code, Codex, and Cursor setup.\n\n## How It Works\n\n```\n  ┌──────────────────────┐\n  │ Artifact Launcher    │\n  │ cognitive-coverage   │\n  │ \u002Fcognitive-coverage  │\n  │      -open.html      │\n  └──────────┬───────────┘\n             │ links\n             ▼\n  ┌──────────────────────┐\n  │   Teaching Guide     │──── quiz answers ────┐\n  │  learning-guide.html │                      │\n  └──────────┬───────────┘                      │\n             │ \"Learn\" links                    ▼\n  ┌──────────┴───────────┐              localStorage\n  │  Coverage Dashboard  │◄──── reads ──────────┘\n  │ cognitive-coverage   │\n  │       .html          │\n  └──────────┬───────────┘\n             │ reads\n  ┌──────────┴───────────┐\n  │  Coverage Manifest   │\n  │ cognitive-coverage   │\n  │       .json          │\n  └──────────────────────┘\n```\n\n1. **Artifact Launcher** opens automatically after generation and links to every output\n2. **Dashboard** loads the manifest and renders coverage status\n3. **Gap report** shows uncovered items with \"Launch Teaching\" buttons\n4. Clicking a button opens the **teaching guide** at the relevant section\n5. Answering quiz questions correctly writes results to **localStorage**\n6. Returning to the dashboard **syncs** quiz results and upgrades coverage\n7. You can also **manually** set status via buttons on each card\n8. **Export** the updated manifest as JSON anytime\n\nSee [docs\u002FHOW-IT-WORKS.md](docs\u002FHOW-IT-WORKS.md) for the full deep dive.\n\n## Domains\n\nThe skill auto-detects the project domain and adapts terminology:\n\n- **`codebase`** — Source code projects (TypeScript, Python, Rust, Go, Java, etc.)\n- **`research`** — Paper collections, literature reviews, datasets\n- **`documentation`** — Wikis, knowledge bases, runbooks, guides\n- **`knowledge`** — General-purpose (anything else)\n\n## Examples\n\nSee the `examples\u002F` directory for sample manifests:\n\n- [`examples\u002Fcodebase\u002F`](examples\u002Fcodebase\u002F) — REST API project\n- [`examples\u002Fresearch\u002F`](examples\u002Fresearch\u002F) — Transformer architecture paper review\n- [`examples\u002Fdocumentation\u002F`](examples\u002Fdocumentation\u002F) — Platform engineering wiki\n\n## Schema\n\nThe manifest format is defined by a JSON Schema:\n\n```\nschemas\u002Fcognitive-coverage.schema.json\n```\n\nUse it to validate manifests programmatically or in CI.\n\n## Project Structure\n\n```\ncognitive-coverage\u002F\n├── README.md                          # This file\n├── LICENSE                            # MIT\n├── CONTRIBUTING.md                    # How to contribute\n├── install.sh                         # Legacy Copilot installer (Unix\u002FmacOS\u002FWSL)\n├── install.ps1                        # Legacy Copilot installer (Windows)\n├── skills\u002F\n│   └── cognitive-coverage\u002F\n│       └── SKILL.md                   # The installable skill instructions\n├── mcp\u002F\n│   ├── server.py                      # Optional MCP stdio server\n│   ├── test_server.py                 # MCP smoke tests\n│   └── pyproject.toml                 # MCP server dependencies\n├── schemas\u002F\n│   └── cognitive-coverage.schema.json # JSON Schema for manifests\n├── examples\u002F\n│   ├── codebase\u002F                      # TypeScript REST API example\n│   ├── research\u002F                      # ML paper review example\n│   ├── documentation\u002F                 # Platform wiki example\n│   ├── mcp-config-claude-code.json    # Claude Code MCP config snippet\n│   └── mcp-config-codex.json          # Codex MCP config snippet\n├── docs\u002F\n│   └── HOW-IT-WORKS.md               # Detailed system documentation\n└── .github\u002F\n    ├── ISSUE_TEMPLATE\u002F\n    │   ├── bug_report.md\n    │   └── feature_request.md\n    └── pull_request_template.md\n```\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nIdeas for contributions:\n- New domain vocabularies (legal, medical, academic)\n- Improved quiz question patterns\n- Dashboard visualization improvements\n- Additional example manifests\n- Installer compatibility improvements\n- Integrations with other tools\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n*Built to fight cognitive debt — one concept at a time.*\n","Cognitive Coverage 是一个用于AI编码代理的技能，旨在帮助测量并缩小任何代码库、研究文献或文档集合中的理解差距。其核心功能包括生成教学指南、覆盖清单、覆盖仪表板和启动器等协调工件，这些工件有助于跟踪、教授、验证以及快速开启对系统的真正理解。项目采用Python编写，支持GitHub Copilot、Claude Code、OpenAI Codex以及其他具备文件访问和Markdown指令支持的LLM驱动代理。它特别适用于那些希望通过增强团队成员对复杂系统理解来减少认知债务的场景，例如在维护大型代码库或知识库时。",2,"2026-06-11 04:03:19","CREATED_QUERY"]