agentsclimarketplace

Debt

Skill Navdeepgambhir9023/nav/skills/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

Install
npx -y skills add Navdeepgambhir9023/nav --skill debt

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

<HARD-GATE> CONSTRAINTS (Must follow): - Do NOT modify source files — read-only scan. `fallow fix` exists but this skill never invokes it. - Do NOT delete or rewrite `debt.nav` entries — append-only. - Do NOT invent findings for a language with no supported analyzer — skip and say so, don't approximate. - Do NOT cross repo boundaries — only files inside `$REPO_ROOT`. </HARD-GATE>

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

LanguageToolStatus
TypeScript / JavaScriptfallow via npx fallowSupported
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

  1. Detect repo root and stack — walk up for .git/; check for package.json/tsconfig.json to confirm TS/JS is present
  2. Run the analyzer — npx fallow audit --format json --quiet scoped to the goal's changed files if run from /loop step 24a-pre, or a full-repo npx fallow --format json if run standalone
  3. Parse findings — each finding becomes one candidate ledger entry
  4. Dedup — skip findings already tracked by fingerprint
  5. Classify — severity/category straight from fallow's own typed output; no reinterpretation
  6. Append — write new entries to debt.nav
  7. Update index — bump debt_count and last_debt_id
  8. Report — print counts by category, top offending files

Checklist

1. Detect Repo Root and Stack

  1. Walk up from cwd looking for .git/ directory; set REPO_ROOT.
  2. Check for TS/JS — does package.json or tsconfig.json exist anywhere under REPO_ROOT (excluding node_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.
  3. 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)

  1. Choose scope:
    • From /loop step 24a-pre (post-goal-CLOSE): run npx fallow audit --gate all --format json --quiet --base <goal-base-sha>, where <goal-base-sha> is the commit the goal branched from (recorded in state.json at goal start). The --base flag is required — fallow audit defaults to comparing against master/main, which is wrong whenever the goal wasn't branched from there, or when there is no meaningful diff yet (verified: without --base on a single-commit repo, changed_files_count came back 0 even 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 than audit — see step 7.
  2. 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).
  3. If fallow is not installed and npx cannot 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-level check (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-level dead_code (same sub-shape as check above, but scoped to the diff), duplication (→ duplication.clone_groups[]), complexity (→ complexity.findings[]), plus a summary/attribution block with aggregate counts only (no per-finding detail) when nothing changed.
  1. 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 under check/dead_code): each entry has path (file-scoped, no line number — this is normal, not a parsing bug) plus kind-specific fields (e.g. unused_files[] has actions[]; 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 has path, category (fallow's own, e.g. "remove_dead_code"), recommendation, effort, confidence, and an evidence{} object — use recommendation as the human-readable description.
    • If npx fallow schema is 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.
  2. 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

  1. Read debt.nav — for each existing entry, extract its fingerprint.
  2. Drop parsed findings whose fingerprint is already tracked.

5. Classify

  1. For each new finding, build the ledger entry:
    • id: D-NNN (string, e.g. "D-003"), where NNN continues from index.last_debt_id (an integer, not the ID string — see step 13)
    • ts: current UTC timestamp
    • goal_id: the just-closed goal id if run from /loop, else null
    • source: "static_analysis:fallow"
    • fingerprint: from step 8
    • category: the array key (unused_files, circular_dependencies, duplication, remove_dead_code, etc.) — fallow's own term, not a reinvented one
    • file: the finding's path
    • line: null unless the specific finding kind actually carries one — do not fabricate a value
    • description: recommendation if present, else a short summary built from the finding's own fields (e.g. "unused file" for a bare unused_files entry)
    • tags: array derived from category

6. Append

  1. Append each new entry as a JSON line to debt.nav.
  2. Update .loop/memory/index.json: debt_count += new entries, last_debt_id = the integer NNN of 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

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

  1. No duplicate fingerprints in debt.nav.
  2. IDs sequential — D-001, D-002, ... with no gaps from re-runs.
  3. index.json updated — debt_count matches debt.nav line count; last_debt_id is the highest assigned.
  4. No source files modified — read-only scan; fallow fix was never invoked.
  5. Unsupported languages reported, not silently skipped — if the repo has Python/Go/Rust files, the report says so.
  6. 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.nav because 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.json or any project config to suppress findings — that's the {OWNER}'s call, not this skill's.

Relationship to Other Skills

SkillWhen it runsRelationship
/debt{OWNER} invokes, or /loop step 24a-pre dispatchesRuns static analysis; appends findings to debt.nav
meta-review/loop step 24aReads mistakes.nav (what broke) — orthogonal to debt
/loop step 24a-preBefore META-REVIEW at every goal CLOSEDispatches /debt scoped to the goal's changes
/loop step 24b (KB UPDATE)After META-REVIEWUpdates kb/principles.md if the goal introduced a new principle pattern
/goal{OWNER}-initiated, separatelyThe 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.

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.