debt-clean
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.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 48
- Forks
- 16
01 前言 Front Matter
- name
- debt-clean
- description
- 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.
- allowed-tools
- Read, Bash, Write, Edit, Grep, Glob
- argument-hint
- [--lane <name>] [--query <text>] [--health healthy|degraded|critical] [--cross-index] [--target-repo both|fak|fak-private] [--top N] (no args = baseline + clean top 1-3 debt hotspots)
- user-invocable
- true
- disable-model-invocation
- false
03 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:
- 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 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
- 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.
04 同仓库更多 Skills
serve-receipt
On-demand research protocol + deterministic receipt for serving a Hugging Face model on a concrete GPU target — fan out research lanes (model facts/files, engine support matrix, serving recipes, KV/state memory math), compute the tiered feasibility verdict with `fak serve-receipt` (never narrated math), and emit a witnessed launch receipt. Use when asked for an "initial config", "serving receipt", or "how do I serve <model> on <GPUs>".
caveman
Ultra-compressed communication mode. Cuts output tokens 65% (measured) by speaking like caveman while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra, wenyan-lite, wenyan-full, wenyan-ultra. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
quality-report
Score the repo quality and emit a report card.
ctx-overlay
Compact the context window and prune the memory store when a session grows too long.
quality-report
Score the repo quality and emit a report card.
ctx-overlay
Compact the context window and prune the memory store when a session grows too long.