| name | gap-detection |
| description | Detect missing docs, undocumented files, project health issues, and coverage gaps on session start or on-demand. Scans for README gaps, TODO/FIXME counts, and test coverage holes. |
| version | 1.0.0 |
| model | sonnet |
| invoked_by | both |
| user_invocable | true |
| tools | ["Read","Bash","Glob","Grep"] |
| agents | ["developer","qa","architect","planner"] |
| category | Validation & Quality |
| tags | ["gap-detection","health-check","documentation","coverage","onboarding"] |
| best_practices | ["Always run on session start for unfamiliar repositories","Report findings as actionable issues, not just counts","Prioritize gaps by blast radius (public API > internal > test helpers)","Cross-reference README vs actual file structure"] |
| error_handling | strict |
| source | builtin |
| trust_score | 100 |
| provenance_sha | 1e137837856ad9a8 |
Gap Detection
Overview
This skill performs a structured health-check scan on session start (or on-demand) to surface:
- Files missing README / documentation headers
- Test coverage gaps (source files without corresponding test files)
- TODO / FIXME counts and locations
- Undocumented public APIs and exports
Use this skill before beginning any significant work in an unfamiliar codebase, or as a recurring quality gate.
When to Use
- Session start in a new or unfamiliar repository
- Before planning a feature to understand existing quality debt
- During code review to identify undocumented additions
- As part of a proactive-audit pipeline
The Iron Law
NO HEALTH REPORT WITHOUT EVIDENCE — EVERY FINDING MUST CITE FILE AND LINE
Never report a gap without a concrete file path and (when applicable) line number. Vague summaries are not actionable.
Workflow
Step 1: Scan for undocumented source files
Command:
find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.cjs" -o -name "*.mjs" -o -name "*.py" \) \
! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/dist/*" ! -path "*/build/*" \
-print | while read f; do
dir=$(dirname "$f")
if [ ! -f "$dir/README.md" ] && [ ! -f "$dir/index.md" ]; then
echo "NO_README: $f"
fi
| -u
