debt-clean
Skill49 starsChanged 14 days agoApache-2.0View on GitHub
One repeatable, evidence-backed pass that retires a bounded batch of maturity debt worst-first across the system's dedicated debt lanes. Features rich queryability (--query, --health), cross-indexes related items (dual-repo companions, tests, runtime-proofs, benchmarks, inbound blast radius), targets high-carrying-cost or degraded hotspots, advances maturity with tests, integration, and benchmarks, re-measures with --compare to prove the denominator was level-set, and commits by explicit path with (fak <leaf>). Use when cleaning or retiring maturity debt across units of work.
In this repository151 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- llms-full.txtllms.txt
- llms.txtllms.txt
- agent-readinessSkill
- appeal-scoreSkill
- bottleneck-mapSkill
- ci-repairSkill
- claim-repro-scoreSkill
- clear-out-wipSkill
- commit-cleanSkill
- conflation-scoreSkill
- cross-validateSkill
- curate-clusterSkill
- debt-orchestratorSkill
- disambiguation-scoreSkill
- dojo-rsi-scoreSkill
- dos-dispatch-loopSkill
- dos-dispatchSkill
- dos-next-upSkill
- dos-replanSkill
- dos-witness-claimSkill
- field-borrowSkill
- fleet-waveSkill
- git-subagent-syncSkill
- goalSkill
- guard-rsi-scoreSkill
- harness-creatorSkill
- harness-gardenSkill
- industry-scoreSkill
- issue-orchestratorSkill
- issue-queueSkill
- issue-triageSkill
- lightgap-scoreSkill
- memory-compactSkill
- milestone-scoreSkill
- modularizeSkill
- negframe-scoreSkill
- opencode-waveSkill
- operator-heaviness-scoreSkill
- persona-scoreSkill
- phased-planSkill
- plan-auditSkill
- quality-scoreSkill
- question-loopSkill
- refresh-cachedoc-numbersSkill
- refresh-readmeSkill
- releaseSkill
- resume-watchdog-auditSkill
- run-it-all-nightSkill
- score-2xSkill
- scorecardSkill
- scout-loopSkill
- signal-firstSkill
- skill-lifecycleSkill
- skill-overlapSkill
- skill-scoreSkill
- slop-scoreSkill
- sota-checkSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 3 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 34
Never attempt a repository-wide sweep in one pass (hundreds of WIP lanes cannot and should not be rushed in a single turn).
- Very specific: line 39
Shift-left proof: Every maturity climb requires genuine disk evidence (passing *_test.go, benchmarks, real runtime wiring), never synthetic …
- Very specific: line 54
Run fak debt-lanes to capture the current state, query candidate work, and audit system health:
- Very specific: line 95
If working in fak (internal/<lane>), check Related.CompanionUnitOfWork for counterpart in fak-private (platform/<lane>).
- Very specific: line 96
If working in fak-private, check counterpart in fak (internal/<lane> or pkg/<lane>).
- Very specific: line 97
Run go run ./cmd/fak-boundary explain <unit_of_work> before making cross-repo edits to ensure 5-gate compliance.
- Very specific: line 102
Check Related.DosTrees declared in dos.toml to verify directory boundaries for subagent task fencing.
- Very specific: line 104
Check Related.ProofWitnesses against internal/maturity/runtime-proofs.json.
- Very specific: line 115
Read the lane's next_action field—this is the exact action required to climb the curve.
- Distinctive: line 190
Run the scorecard against the saved baseline to prove the drop:
- Very specific: line 208
Follow trunk discipline: stage only the explicit paths modified for this single unit of work.
- Distinctive: line 224
Verify git status shows your lane is committed and no peer WIP was touched.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/debt-clean — retire maturity debt worst-first in bounded batches
What this does. Every unit of work (feature, module, leaf) in the system carries a dedicated debt lane scored on a continuous 0.0–10.0 maturity curve. When new work is added at a partial maturity (e.g. 1/10 stub), it immediately enters the production grade denominator as debt with an accrued carrying cost.
This skill executes a bounded, disciplined cleaning pass: query and baseline the debt lanes, cross-index related things (dual-repo companions, dependents, proofs, benchmarks), run pre-flight health diagnostics, pick 1–3 high-leverage hotspots (worst carrying cost, critical compounding interest, or degraded health), fulfill the exact next action that advances the maturity curve, prove the debt dropped and health upgraded with
--compare, and commit by explicit path.
The shape: query & baseline debt lanes → cross-index related things & pre-flight health → pick bounded batch (1–3 units) → execute next action
(tests/integration/benchmarks/clean bloat) → verify package → prove debt drop & health upgrade with --compare → commit by
explicit path.
The Rule of Bounded Batches
Never attempt a repository-wide sweep in one pass (hundreds of WIP lanes cannot and should not be rushed in a single turn). Enforce strict scoping:
- Max 1–3 units of work per batch: Focus on 1–3 closely related leaves or a single critical hotspot.
- Shift-left proof: Every maturity climb requires genuine disk evidence (passing
*_test.go, benchmarks, real runtime wiring), never synthetic markers or mock-only claims. - No comment gaming; excess comments is BAD debt: Comments are NOT tracked as positive debt retirement. Do not add formulaic "Contract:", "Invariant:", or "Fail-closed:" comment headers or restate syntax. In fact, excess comments and comment bloat (>35% comment ratio or formulaic keyword clutter) are penalized as BAD debt with interest rate penalties.
- Denominator honesty: Advancing maturity increases realized points without shrinking the denominator, genuinely raising the production-grade percentage.
- Multi-dimensional health upgrade: Debt retirement must elevate the lane's health status
from
degradedorcriticaltowardhealthy, resolving flagged issue tokens.
Step 1 — Measure Baseline & Query Health
Run fak debt-lanes to capture the current state, query candidate work, and audit system health:
# Capture full baseline:
fak debt-lanes --json > baseline.json
fak debt-lanes --top 5
# Query lanes by keyword (matches lane name, unit of work, companion, drivers, or health issues):
fak debt-lanes --query <keyword> --top 5
# Filter lanes by multi-dimensional health verdict (healthy, degraded, critical):
fak debt-lanes --health degraded,critical --top 5
# Cross-index related things, dual-repo companions, and blast radius:
fak debt-lanes --cross-index --top 10Multi-Dimensional Lane Health Dimensions
healthy: Score >= 0.85, test passing, clean comment hygiene, integrated into production graph, documented/benchmarked if core, low carrying interest.degraded: Untested stubs (missing_tests), excess comment bloat (comment_ratio > 35%or formulaic keyword noise), disconnected wiring (integrated=false), unbenchmarked, or unproven in runtime.critical: Compounding carrying cost (>25% interest rate) or untested core paths (criticality=core && has_tests=false) with high inbound dependents.
Note the headline figures:
- Production Grade: current letter and percentage (e.g.
Grade C, 75.4%). - Fleet Health: healthy, degraded, and critical counts with average health score.
- Denominator Points: total production baseline points.
- Total Debt: total principal + carrying cost.
- Top Hotspots: lanes carrying the highest carrying cost or highest maturity gap.
Step 2 — Cross-Index Related Things & Select Target (1–3 Units)
Inspect the specific target's status, evidence, health findings, and cross-indexed artifacts:
fak debt-lanes --lane <lane-name> --jsonCross-Indexing Checklist for Target Lane
- Dual-Repo Companion:
- If working in
fak(internal/<lane>), checkRelated.CompanionUnitOfWorkfor counterpart infak-private(platform/<lane>). - If working in
fak-private, check counterpart infak(internal/<lane>orpkg/<lane>). - Run
go run ./cmd/fak-boundary explain <unit_of_work>before making cross-repo edits to ensure 5-gate compliance.
- If working in
- Blast Radius & Inbound Dependents:
- Inspect
Related.Dependents(packages importing this lane). Core leaves with >10 dependents require non-breaking public APIs. - Inspect
Related.Dependencies(packages imported by this lane).
- Inspect
- Registered DOS Trees:
- Check
Related.DosTreesdeclared indos.tomlto verify directory boundaries for subagent task fencing.
- Check
- Witness Proofs & Benchmarks:
- Check
Related.ProofWitnessesagainstinternal/maturity/runtime-proofs.json. - Check
Related.BenchmarkWitnessesagainstBENCHMARK-AUTHORITY.md.
- Check
Choose targets based on leverage:
- Option A: High Carrying Risk (Critical Compounding Interest):
Lanes where
interest.band == "critical"(>25% rate) orhealth.status == "critical". - Option B: Untested / Skeleton Stubs (Highest Maturity Gap):
Lanes sitting at
0.0or1.0/8.0(proposedorstub). Adding core types and tests jumps maturity from1.0to4.0+. - Option C: Comment Bloat / Hygiene Cleanup:
Lanes flagged with
excess_commentswhere pruning formulaic comments restores clean structure and cuts bad debt interest.
Read the lane's next_action field—this is the exact action required to climb the curve.
Step 3 — Delegate to Subagent (Keep Coordinator Context Clean)
Per AGENTS.md, the primary agent coordinates; substantive investigation, code editing, and test runs are delegated to isolated subagents via the task tool so coordinator context stays clean and focused.
Launch a targeted subagent:
{
"subagent_type": "general",
"description": "Clean debt in <lane>",
"prompt": "You are an isolated worker advancing the maturity curve for <unit_of_work> (internal/<lane> or pkg/<lane>).\nGoal: fulfill the exact next action: <next_action>.\nTarget Directory: <unit_of_work>\nBoundaries: Edit ONLY files inside <unit_of_work>/. Do not touch sibling packages.\nVerification: Execute `go test -v ./<unit_of_work>` and `go vet ./<unit_of_work>`.\nReturn Contract: Return a compact receipt with: (1) files modified/created, (2) test result receipt, (3) brief 1-line rationale. Do not return full command logs."
}The subagent executes the concrete work needed:
- If missing tests (
HasTests == false): Writes real unit tests (<name>_test.go) in<unit_of_work>/. Covers positive and negative branches, edge cases, and ensuresgo test ./<unit_of_work>/...passes cleanly. - If missing implementation (
HasCode == falseor stub): Implements core functions, types, and logic in<unit_of_work>/. Adheres to existing patterns and keeps the package focused. - If unintegrated (
Integrated == false): Connects the package into production commands or registration graph. - If undogfooded (
Dogfooded == false): Executes real runtime path and captures passing proof ininternal/maturity/runtime-proofs.json. - If unbenchmarked (
Benchmarked == false): Adds substantiveBenchmark*functions withb.Nloops measuring production operations. - If carrying excess comments (
ExcessComments == true): Prunes formulaic comment bloat, redundant syntax explanations, and keyword clutter. Code must be clean and self-documenting; invariants belong in tests and code assertions. NEVER add formulaic "Contract:", "Invariant:", "Fail-closed:" comments.
Step 4 — Coordinator Independent Witnessing
The coordinator does NOT trust worker narration—it independently witnesses the result (the dos-witness-claim invariant):
- Verify toolchain execution:
- For public
fakunits (internal/<target>orpkg/<target>):go vet ./<unit_of_work> go test -v ./<unit_of_work> - For private
fak-privateunits (platform/<target>):go -C ..\fak-private vet ./platform/<target> go -C ..\fak-private test -v ./platform/<target>
- For public
- Verify maturity curve ascent & health upgrade:
fak debt-lanes --lane <target> --json
Verify that:
Maturityincreased (e.g. from1.0or2.0to4.0or7.5+).MaturityGapdecreased.DebtPrincipalandCarryingCostdropped.RealizedContributionincreased.Health.Statusimproved (e.g. fromcriticaltodegraded, ordegradedtohealthy).Health.Issuesresolved target issue tokens (e.g.missing_tests,excess_comments,disconnected_wiring).
Step 5 — Re-Measure and Prove Debt Drop & Health Upgrade
Run the scorecard against the saved baseline to prove the drop:
fak debt-lanes --compare baseline.json
fak debt-lanes --lane <target>Confirm:
Total Debtshows a negative delta (-X.X pts).Health Statusshows the lane upgraded with no regression in companion lanes.Production Gradepercentage improved or held steady.Denominatorremained stable (no work was deleted to cheat the score).WIP Dilutiondecreased.
Step 6 — Commit Cleanly by Explicit Path
Follow trunk discipline: stage only the explicit paths modified for this single unit of
work. Include a Conventional-Commits subject, signed-off DCO (-s), and the required repo trailer:
- For public
fakcommits:fak sync reconcile --apply python tools/scrub_public_copy.py --audit-staged --root . fak commit --path <unit_of_work> -m "fix(<target>): advance maturity curve and retire debt (fak <target>)" [--push] fak sync push - For private
fak-privatecommits:git -C ..\fak-private add platform/<target> git -C ..\fak-private commit -s -m "fix(<target>): advance maturity curve and retire debt (fak-private <target>)" -- platform/<target>
Verify git status shows your lane is committed and no peer WIP was touched.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

