Documentation Index
Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt
Use this file to discover all available pages before exploring further.
Coverage model
For every file in a scanned repository, Driftless checks whether any topic covers it deterministically, with no LLM involved. The result is a coverage map that shows exactly what is documented and what is a knowledge gap.
Match specificity tiers
Every file falls into one of four tiers, based on how strongly a topic anchors to it:
| Tier | Mechanism | Strength |
|---|
| file | Topic has this exact file path in where_files | Strong / direct |
| pattern | Topic’s glob pattern matches this file | Indirect |
| repo | Topic is scoped to this repository but has no file or pattern match | Weak |
| none | No topic covers this file | Gap |
file anchor and a pattern anchor, it counts as file-covered.
Risk heuristic
Files that match any of these criteria are flagged as high-risk:
- Path or filename contains:
auth, admin, billing, payment, webhook, token, secret, password
- Entrypoint files (controllers, route handlers, server actions) without detected guards
High-risk uncovered files get prioritized in coverage reports.
Coverage status per file
| Status | Meaning |
|---|
| covered | At least one active topic covers this file |
| partial | Covered only by a weak (repo) match |
| gap | No topic covers this file, but risk is normal |
| critical-gap | No topic covers this file, and it’s high-risk |
| empty | No scan data exists for this file yet |
Recommended actions
Based on coverage and risk, Driftless suggests actions:
| Action | Trigger |
|---|
| document-now | High-risk file with no coverage |
| reattach-or-remove | Orphaned topic that still has anchored files |
| refresh-stale | Topic is stale with active anchors |
| add-topic | Cluster of uncovered files in same module |
| review-suggested | Auto-generated topic awaiting review |
| promote-draft | Draft topic with reviewed content |
Coverage in practice
Load per-file coverage for the files you’re about to edit:
driftless context load --files "src/auth/guard.ts,src/users/service.ts"
- Which topics cover each file (with match tier)
- Coverage status for each file
- Recommended actions for gaps
Coverage on the dashboard
The architecture map overlay colors module nodes by coverage:
- Green - Covered (at least one file-level or pattern-level topic)
- Yellow - Partial (repo-level only)
- Red - Gap (no coverage)
- Red pulsing - Critical gap (high-risk, no coverage)
Click any node to see which topics cover it and what actions are recommended.
Health score
The workspace health score in the dashboard weights coverage heavily:
| Factor | Weight |
|---|
| Context coverage (% of files covered) | 55% |
| Freshness (% of topics not stale) | 25% |
| Stale ratio (stale vs. total topics) | 20% |
driftless context doctor # full health audit with breakdown
