Debt
Detect real antipatterns automatically via static analysis and append them to `.loop/memory/debt.nav`, so technical debt is discovered and tracked instead of relying on anyone remembering to flag it. Use when the user says "nav debt", "/debt", "what antipatterns do we have", "debt ledger", "find dead code", "find duplication". Currently supports TypeScript/JavaScript via `fallow` (https://github.com/fallow-rs/fallow). Other languages are explicitly out of scope until a real project needs them — see "Language Support" below. One-shot report, idempotent re-run (won't re-append findings already tracked by the same fingerprint).From its SKILL.md
npx -y skills add Navdeepgambhir9023/nav --skill debtAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
12.7 KB, as published. Nobody here has run it
{OWNER} — who Nav is addressing
Wherever this skill says {OWNER}, substitute the label field from
.loop/config.json. Default: founder. Capitalize it when it begins a
sentence or heading, and never emit the literal string {OWNER} to the user.
This is vocabulary only. No gate, threshold, default, or question differs
between profiles — an engineer and a founder get exactly the same engine.
If .loop/config.json is missing or unreadable, use "founder" and continue;
never halt on it.
/debt — Detect Antipatterns Into the Ledger
/debt finds real, undeclared antipatterns via static analysis and
records them in one ledger, so technical debt is visible and counted
instead of scattered across a codebase where nobody looks.
Anti-Pattern: "Nobody Remembered to Flag It"
Debt that depends on a human remembering to leave a comment at the
moment they wrote the shortcut always undercounts — legacy code
predates the convention, and code written under deadline pressure is
exactly the code least likely to get annotated. /debt instead finds
what's actually there: dead code, duplication, complexity hotspots,
circular dependencies, boundary violations. Detection doesn't depend
on anyone's memory.
Language Support
| Language | Tool | Status |
|---|---|---|
| TypeScript / JavaScript | fallow via npx fallow | Supported |
| Python, Go, Rust, others | — | Not yet — skip and report the gap, don't fake it |
Adding a language means adding one section to Step 2 below with its own detection + invocation + parse logic. Do not build ahead of an actual project needing it (Ladder rung 1 — YAGNI).
Process Summary
- Detect repo root and stack — walk up for
.git/; check forpackage.json/tsconfig.jsonto confirm TS/JS is present - Run the analyzer —
npx fallow audit --format json --quietscoped to the goal's changed files if run from/loopstep 24a-pre, or a full-reponpx fallow --format jsonif run standalone - Parse findings — each finding becomes one candidate ledger entry
- Dedup — skip findings already tracked by fingerprint
- Classify — severity/category straight from fallow's own typed output; no reinterpretation
- Append — write new entries to
debt.nav - Update index — bump
debt_countandlast_debt_id - Report — print counts by category, top offending files
Checklist
1. Detect Repo Root and Stack
- Walk up from cwd looking for
.git/directory; setREPO_ROOT. - Check for TS/JS — does
package.jsonortsconfig.jsonexist anywhere underREPO_ROOT(excludingnode_modules)? If yes, TS/JS analysis runs. If the repo has no TS/JS at all, report "no supported language detected" and stop — do not fall back to scanning for anything else. - Note other languages present (Python, Go, Rust files, etc.) but do not attempt to analyze them — report them under "not yet supported" in the final output so the {OWNER} knows the gap exists.
2. Run the Analyzer (TypeScript/JavaScript)
- Choose scope:
- From
/loopstep 24a-pre (post-goal-CLOSE): runnpx fallow audit --gate all --format json --quiet --base <goal-base-sha>, where<goal-base-sha>is the commit the goal branched from (recorded instate.jsonat goal start). The--baseflag is required —fallow auditdefaults to comparing againstmaster/main, which is wrong whenever the goal wasn't branched from there, or when there is no meaningful diff yet (verified: without--baseon a single-commit repo,changed_files_countcame back0even with real dead code present). - Standalone {OWNER} invocation: run
npx fallow --format json(full pipeline) for a whole-repo view. This has a different top-level JSON shape thanaudit— see step 7.
- From
- Handle exit codes —
0= clean,1= findings present (expected, not an error),2= real tool error (report it, do not silently continue as if clean). - If
fallowis not installed andnpxcannot fetch it (offline, registry blocked) — report the failure explicitly. Do not proceed with a partial or fabricated result.
3. Parse Findings
Verified schema (fallow 2.88.2, schema_version: 7) — the two commands nest findings differently:
npx fallow --format json(full pipeline) → top-levelcheck(dead code + circular deps + boundary violations, e.g.check.unused_files[],check.circular_dependencies[]),dupes(→dupes.clone_groups[]),health(→health.targets[], complexity/hotspot recommendations).npx fallow audit ...(changed-file gate) → top-leveldead_code(same sub-shape ascheckabove, but scoped to the diff),duplication(→duplication.clone_groups[]),complexity(→complexity.findings[]), plus asummary/attributionblock with aggregate counts only (no per-finding detail) when nothing changed.
- For each finding, extract what's actually present — do not assume a uniform shape:
- Dead code (
unused_files,unused_exports,unused_types,unused_dependencies,unused_enum_members,unused_class_members,circular_dependencies,re_export_cycles,boundary_violations— one array per kind undercheck/dead_code): each entry haspath(file-scoped, no line number — this is normal, not a parsing bug) plus kind-specific fields (e.g.unused_files[]hasactions[];unused_exports[]would carry the export name). Category = the array's own key name (e.g."unused_files"), used verbatim. - Duplication (
dupes.clone_groups[]/duplication.clone_groups[]): each clone group lists the files/ranges involved. Category ="duplication". - Complexity/health (
health.targets[]/complexity.findings[]): each entry haspath,category(fallow's own, e.g."remove_dead_code"),recommendation,effort,confidence, and anevidence{}object — userecommendationas the human-readable description. - If
npx fallow schemais available, run it once and prefer its typed manifest over this list — fallow versions may add fields; this skill's job is to read what's there, not force it into an invented flat shape.
- Dead code (
- Compute a fingerprint per finding:
sha1(source_array_key + path + JSON.stringify(finding))— path-level, not line-level, since line numbers aren't reliably present. This is the dedup key.
4. Dedup
- Read
debt.nav— for each existing entry, extract itsfingerprint. - Drop parsed findings whose fingerprint is already tracked.
5. Classify
- For each new finding, build the ledger entry:
id:D-NNN(string, e.g."D-003"), whereNNNcontinues fromindex.last_debt_id(an integer, not the ID string — see step 13)ts: current UTC timestampgoal_id: the just-closed goal id if run from/loop, elsenullsource:"static_analysis:fallow"fingerprint: from step 8category: the array key (unused_files,circular_dependencies,duplication,remove_dead_code, etc.) — fallow's own term, not a reinvented onefile: the finding'spathline:nullunless the specific finding kind actually carries one — do not fabricate a valuedescription:recommendationif present, else a short summary built from the finding's own fields (e.g. "unused file" for a bareunused_filesentry)tags: array derived fromcategory
6. Append
- Append each new entry as a JSON line to
debt.nav. - Update
.loop/memory/index.json:debt_count+= new entries,last_debt_id= the integerNNNof the highest assigned ID (e.g.2, not"D-002"— verified this ambiguity actually trips a fresh run if left unstated),last_updated= now.
7. Report
- Print:
/debt report ──────────── Language support: TypeScript/JavaScript (fallow) Not yet supported: <other languages detected in repo, if any> Scanned: fallow audit, <N> files in scope New findings: <M> Already tracked: <K> By category: dead-code: <count> duplication: <count> complexity: <count> circular-dependency: <count> boundary-violation: <count> New entries: <id> <category> <file>:<line> <description> ...
Process Flow
digraph debt {
"Detect repo root + stack" [shape=box];
"TS/JS present?" [shape=diamond];
"Report: no supported language" [shape=box];
"Run npx fallow (audit or full)" [shape=box];
"Parse findings + fingerprint" [shape=box];
"Read existing debt.nav" [shape=box];
"Drop already-tracked (dedup)" [shape=box];
"Classify + build entries" [shape=box];
"Append new entries to debt.nav" [shape=box];
"Update index.json" [shape=box];
"Print report" [shape=doublecircle];
"Detect repo root + stack" -> "TS/JS present?";
"TS/JS present?" -> "Report: no supported language" [label="no"];
"TS/JS present?" -> "Run npx fallow (audit or full)" [label="yes"];
"Run npx fallow (audit or full)" -> "Parse findings + fingerprint";
"Parse findings + fingerprint" -> "Read existing debt.nav";
"Read existing debt.nav" -> "Drop already-tracked (dedup)";
"Drop already-tracked (dedup)" -> "Classify + build entries";
"Classify + build entries" -> "Append new entries to debt.nav";
"Append new entries to debt.nav" -> "Update index.json";
"Update index.json" -> "Print report";
}
The terminal state is the printed report.
Self-Review Checklist
After running:
- No duplicate fingerprints in
debt.nav. - IDs sequential —
D-001,D-002, ... with no gaps from re-runs. index.jsonupdated —debt_countmatchesdebt.navline count;last_debt_idis the highest assigned.- No source files modified — read-only scan;
fallow fixwas never invoked. - Unsupported languages reported, not silently skipped — if the repo has Python/Go/Rust files, the report says so.
- Report printed — counts by category and new entries visible.
Red Flags — STOP
- About to run
fallow fix(or any auto-fix) — that's a {OWNER} decision via a new/goal, not this skill's job. - About to delete an entry from
debt.navbecause it looks stale — resolve via a new goal, not retroactive deletion. - About to approximate a finding for an unsupported language because "it's probably similar" — report the gap instead.
- About to modify
.fallowrc.jsonor any project config to suppress findings — that's the {OWNER}'s call, not this skill's.
Relationship to Other Skills
| Skill | When it runs | Relationship |
|---|---|---|
/debt | {OWNER} invokes, or /loop step 24a-pre dispatches | Runs static analysis; appends findings to debt.nav |
meta-review | /loop step 24a | Reads mistakes.nav (what broke) — orthogonal to debt |
/loop step 24a-pre | Before META-REVIEW at every goal CLOSE | Dispatches /debt scoped to the goal's changes |
/loop step 24b (KB UPDATE) | After META-REVIEW | Updates kb/principles.md if the goal introduced a new principle pattern |
/goal | {OWNER}-initiated, separately | The only place a debt.nav entry actually gets resolved — /debt never fixes anything itself |
The Bottom Line
Debt that depends on someone remembering to flag it will always be
undercounted. /debt finds what's actually there.
The skill that silently "fixes" what it finds is the skill that breaks
the contract. Detect, dedup, append, report. The {OWNER} decides what
to do with each finding — usually by opening a /goal to resolve it —
not this skill.