agentleFS
anthony-chaudharyanthony-chaudhary/fak/.agents/skills/debt-clean/SKILL.md

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.

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

    Never attempt a repository-wide sweep in one pass (hundreds of WIP lanes cannot and should not be rushed in a single turn).

    line 34
  2. Very specific:

    Shift-left proof: Every maturity climb requires genuine disk evidence (passing *_test.go, benchmarks, real runtime wiring), never synthetic …

    line 39
  3. Very specific:

    Run fak debt-lanes to capture the current state, query candidate work, and audit system health:

    line 54
  4. Very specific:

    If working in fak (internal/<lane>), check Related.CompanionUnitOfWork for counterpart in fak-private (platform/<lane>).

    line 95
  5. Very specific:

    If working in fak-private, check counterpart in fak (internal/<lane> or pkg/<lane>).

    line 96
  6. Very specific:

    Run go run ./cmd/fak-boundary explain <unit_of_work> before making cross-repo edits to ensure 5-gate compliance.

    line 97
  7. Very specific:

    Check Related.DosTrees declared in dos.toml to verify directory boundaries for subagent task fencing.

    line 102
  8. Very specific:

    Check Related.ProofWitnesses against internal/maturity/runtime-proofs.json.

    line 104
  9. Very specific:

    Read the lane's next_action field—this is the exact action required to climb the curve.

    line 115
  10. Distinctive:

    Run the scorecard against the saved baseline to prove the drop:

    line 190
  11. Very specific:

    Follow trunk discipline: stage only the explicit paths modified for this single unit of work.

    line 208
  12. Distinctive:

    Verify git status shows your lane is committed and no peer WIP was touched.

    line 224

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/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:

  1. Max 1–3 units of work per batch: Focus on 1–3 closely related leaves or a single critical hotspot.
  2. Shift-left proof: Every maturity climb requires genuine disk evidence (passing *_test.go, benchmarks, real runtime wiring), never synthetic markers or mock-only claims.
  3. 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.
  4. Denominator honesty: Advancing maturity increases realized points without shrinking the denominator, genuinely raising the production-grade percentage.
  5. Multi-dimensional health upgrade: Debt retirement must elevate the lane's health status from degraded or critical toward healthy, 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 10

Multi-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> --json

Cross-Indexing Checklist for Target Lane

  1. Dual-Repo Companion:
    • If working in fak (internal/<lane>), check Related.CompanionUnitOfWork for counterpart in fak-private (platform/<lane>).
    • If working in fak-private, check counterpart in fak (internal/<lane> or pkg/<lane>).
    • Run go run ./cmd/fak-boundary explain <unit_of_work> before making cross-repo edits to ensure 5-gate compliance.
  2. 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).
  3. Registered DOS Trees:
    • Check Related.DosTrees declared in dos.toml to verify directory boundaries for subagent task fencing.
  4. Witness Proofs & Benchmarks:
    • Check Related.ProofWitnesses against internal/maturity/runtime-proofs.json.
    • Check Related.BenchmarkWitnesses against BENCHMARK-AUTHORITY.md.

Choose targets based on leverage:

  • Option A: High Carrying Risk (Critical Compounding Interest): Lanes where interest.band == "critical" (>25% rate) or health.status == "critical".
  • Option B: Untested / Skeleton Stubs (Highest Maturity Gap): Lanes sitting at 0.0 or 1.0/8.0 (proposed or stub). Adding core types and tests jumps maturity from 1.0 to 4.0+.
  • Option C: Comment Bloat / Hygiene Cleanup: Lanes flagged with excess_comments where 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 ensures go test ./<unit_of_work>/... passes cleanly.
  • If missing implementation (HasCode == false or 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 in internal/maturity/runtime-proofs.json.
  • If unbenchmarked (Benchmarked == false): Adds substantive Benchmark* functions with b.N loops 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):

  1. Verify toolchain execution:
    • For public fak units (internal/<target> or pkg/<target>):
      go vet ./<unit_of_work>
      go test -v ./<unit_of_work>
    • For private fak-private units (platform/<target>):
      go -C ..\fak-private vet ./platform/<target>
      go -C ..\fak-private test -v ./platform/<target>
  2. Verify maturity curve ascent & health upgrade:
    fak debt-lanes --lane <target> --json

Verify that:

  • Maturity increased (e.g. from 1.0 or 2.0 to 4.0 or 7.5+).
  • MaturityGap decreased.
  • DebtPrincipal and CarryingCost dropped.
  • RealizedContribution increased.
  • Health.Status improved (e.g. from critical to degraded, or degraded to healthy).
  • Health.Issues resolved 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 Debt shows a negative delta (-X.X pts).
  • Health Status shows the lane upgraded with no regression in companion lanes.
  • Production Grade percentage improved or held steady.
  • Denominator remained stable (no work was deleted to cheat the score).
  • WIP Dilution decreased.

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 fak commits:
    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-private commits:
    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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.