quality-score
Skill49 starsChanged 14 days agoApache-2.0View on GitHub
One repeatable RSI pass over CODE quality — the code-side counterpart of refresh-readme. Runs the code-quality scorecard (tools/code_quality_scorecard.py), reads the code-debt work-list, retires debt worst-first using ONLY the safe, genuine classes (gofmt, real tests for untested packages, safe god-function extraction), re-measures to PROVE the number dropped, grounds the ship in DOS (dos commit-audit on the new commit, dos review for the ship_integrity KPI), and commits by explicit path. Use to baseline code quality, drive the code-2x program (halve code-debt, then. Use when this named workflow matches the task.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- SAQLAINAP/GitClaw-Agenttheir own version, first seen Apr 5, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- SAQLAINAP/GitClaw-Agent★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
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-cleanSkill
- 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
- 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
5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 79
Record the baseline: Before touching anything, write down code_debt = N and score = S.
- Very specific: line 109
Never edit the frozen ABI (internal/abi) or add a dependency to move a number.
- Very specific: line 122
If it fails or won't build, fix or drop it.
- Very specific: line 162
dos commit-audit HEADis the gate: If it says subject-only / CLAIM_UNWITNESSED, your diff doesn't back your subject — reword the subject … - Very specific: line 204
After a burst of new cmd/* tools or benchmarks (they land untested → tests debt spikes.
≈ “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
/quality-score — make "better code" provable, then prove it moved
What this does. The docs have a measuring stick (
docs_scorecard.py+/refresh-readme); until this skill, the Go code had none — so "cleaner code", "better architecture", "more tested" were unfalsifiable claims with no number to move. This is the code's checking layer. It makes "improve the code" a repeatable, evidence-grounded pass: measure the code-debt, retire it worst-first with safe genuine fixes, then re-measure to prove the number dropped — and ground the proof in DOS, not in a sentence.
The shape: run the scorecard → read the code-debt work-list → retire debt worst-first (safe classes only) → re-measure and prove the drop → DOS-witness the commit → commit ONLY your lane by explicit path.
The headline metric is code-debt: the count of concrete, re-derivable HARD defects across ten KPIs. The program target is the code-2x: halve code-debt, then halve again — recursive self-improvement with a number that can't lie, because every unit is re-derived from disk and the Go toolchain on each pass.
The measure (ten KPIs, each 0–100, deterministic — same tree → same score)
tools/code_quality_scorecard.py folds these into a composite score + the
code-debt integer. HARD KPIs emit code-debt (they gate ok); SOFT KPIs
score but never gate.
| KPI | HARD/SOFT | one unit of code-debt is… |
build | HARD | go build ./... does not exit 0 |
vet | HARD | a go vet ./... diagnostic |
format | HARD | a file gofmt -l reports as unformatted |
deps | HARD | an external require in go.mod (or a present go.sum) — the zero-dep invariant broke |
honesty | HARD | a - [ line in CLAIMS.md not carrying exactly one [SHIPPED]/[SIMULATED]/[STUB] tag |
architecture | HARD | an egregious god-file (>1500 lines) or god-function (>200 lines) |
tests | HARD | a non-trivial package (≥4 funcs) with zero _test.go |
ship_integrity | HARD | a RESIDUAL commit in dos review — a claim the diff could not witness |
godoc | SOFT | an undocumented exported symbol (advisory — see anti-gaming) |
hygiene | SOFT | a TODO/FIXME/HACK/XXX marker in shipped code (advisory — see anti-gaming) |
godoc and hygiene are SOFT on purpose. The cheap way to move either is
gaming, not quality: doc-comment spam (// X does X) for godoc, and DELETING
a // TODO (hiding the gap, not closing it) for hygiene — and this repo keeps
an honest [STUB] ledger where a "TODO: implement" marker is a feature of
that honesty. They score (a doc-poor or marker-heavy tree grades lower) but they
never gate, so the pass is never rewarded for cosmetic churn. Same WARN/HARD
split docs_scorecard draws for jargon.
Step 1 — Run the scorecard (it builds your work-list)
From the repo root:
python tools/code_quality_scorecard.py # human scorecard (per-KPI + work-list)
python tools/code_quality_scorecard.py --json # machine payload (the loop uses this)It exits non-zero whenever code-debt > 0. Read corpus.score, corpus.code_debt,
and corpus.breakdown (per-KPI debt, worst first). The per-KPI defects arrays
ARE the work-list.
Fast/static-only mode (skips go build/vet/gofmt): --no-toolchain. Skip
the DOS probe: --no-dos. The default (full) is what you commit against.
Record the baseline. Before touching anything, write down code_debt = N and
score = S. The whole point is to prove the delta, so you need the before-number.
Step 2 — Retire code-debt worst-first, using SAFE GENUINE classes only
Attack the heaviest KPI first (corpus.breakdown[0]), but only via fixes that
are safe on a shared trunk and genuine (they improve the code, not just the
number). In rough order of safety:
format(safest).gofmt -w <the flagged files>. Semantics-preserving;go build ./...stays green. Confirm only those files are clean and not peer-modified first (git status --short <files>).tests(safe + high-value). For each untested package, find a PURE, deterministic function (math, parsing, formatting, scoring — no GPU, network, or model-file) and write ONE real, table-driven test with assertions that can actually FAIL. Same package clause (package mainforcmd/*). Be honest: if a package is only amain()wiring flags + I/O into already-testedinternal/packages, it has no testable seam — leave it and say so. A fabricatedassert truetest is worse than no test, and it is exactly the gaming the SOFT KPIs exist to refuse. Validate (Step 3) before trusting it.vet/build. Fix the diagnostic at its cause; never silence it.architecture(RISKY — care). Extract a god-function's body into a testable helper (which also retires atestsunit). This is real refactoring: do it in ONE lane, keep behavior identical, and validate hard. If you can't do it safely this pass, leave it for a focused pass — do NOT half-do a refactor.ship_integrity. A RESIDUAL is usually a historical commit (e.g. a regenerated binary asset the diff can't witness); it ages out of the window as the trunk advances. You don't "fix" someone else's past commit — you ensure YOUR commits are diff-witnessed (Step 5), so you never add residual.
Never edit the frozen ABI (internal/abi) or add a dependency to move a number.
Step 3 — Validate every change (the honesty gate)
Native go test is OS-blocked on the Windows dev box, so validate under WSL:
go build ./... # compiles (catches structural breaks)
go vet ./... # typechecks incl. _test.go files
wsl -e bash -lc 'cd /mnt/c/work/fak && go test ./<changed-pkg>/... -count=1'A new test you have not RUN is not done — it might not even compile. Run it.
If it fails or won't build, fix or drop it; never ship a red/uncompiling test.
Re-run gofmt -l <your new files> — your additions must be gofmt-clean (the
format KPI will catch them next pass otherwise).
Step 4 — Re-measure and PROVE the drop
python tools/code_quality_scorecard.py --jsonConfirm code_debt dropped from N toward your target and score rose. State the
delta plainly: code-debt N → M (−k), score S → S'. The code-2x bar for a pass
is halving the actionable hard-debt (doubling a 70-ish score is impossible —
it caps at 100, so the honest "2×" lives on the debt axis, the way the docs
program states "cut doc-debt 100×"). Regenerate the committed snapshot:
python tools/code_quality_scorecard.py --markdown --stamp YYYY-MM-DD > docs/CODE-QUALITY-SCORECARD.md(Use the Bash tool's > — it preserves UTF-8. A PowerShell > re-encodes to
UTF-16 and mangles the ·/×/— glyphs.)
Step 5 — Ground the ship in DOS, then commit ONLY your lane
The ship_integrity KPI already reads dos review — but witness YOUR OWN
commit too, so "I fixed it" is backed by evidence the committing agent can't
author:
fak sync reconcile --apply
fak commit --path <your explicit paths> -m "<conventional subject>" -m "<body: N→M debt, what changed>" -m "(fak <leaf>)"
dos commit-audit HEAD # MUST print [diff-witnessed] / verdict OK
fak sync push- Subject honesty. New tests + fmt →
test(<scope>):orstyle(fmt):. A refactor that changes structure →refactor(<scope>):. Don't usefeat(/fix(for a test/format pass — keep the prefix honest to what changed. End every ship commit with a(fak <leaf>)trailer so thedos verifyreferee binds it. dos commit-audit HEADis the gate. If it sayssubject-only/ CLAIM_UNWITNESSED, your diff doesn't back your subject — reword the subject to what the diff actually did (or add the missing change). A[diff-witnessed]verdict is the green light. This is the same rung theship_integrityKPI scores, applied to your own work.- Shared-trunk discipline. Stay on
main(theOFF_TRUNKguard refuses a branch). Commit by explicit path viafak commit --path. If a peer'sMERGE_HEADis set (cannot do a partial commit during a merge): wait for it to clear, then re-try the pathspec commit. Never force-push.
The RSI loop (why this is a self-improvement skill, not a one-shot)
Each pass: measure → retire the heaviest safe debt → prove the drop → commit
witnessed. Run it again next pass and the new heaviest KPI surfaces — the loop
walks the debt down monotonically because the number is re-derived from disk
every time, so it can't drift or be talked past. Halve, then halve again. On a
/loop cadence it keeps the kernel from re-accreting debt between releases.
The discipline that makes it RSI and not vibes: every pass moves a number that
is grounded in evidence the agent did not author — the Go toolchain's exit
codes (build/vet/format), a go test red→green under WSL (tests), and
dos review / dos commit-audit (ship_integrity). The score is the gauge;
the witnesses are why you can trust it moved.
Anti-gaming laws (internalize these — the measure is only as honest as the pass)
- Never write a vacuous test to drop
testsdebt. A test must be able to FAIL on a real regression. No testable seam → leave it and say so. - Never delete a
// TODOto "improve"hygiene. It's SOFT for this exact reason — close the gap or leave the honest marker. - Never spam doc comments to move
godoc. Also SOFT, also on purpose. - Never silence a
vetdiagnostic or//nolintpast it. Fix the cause. - Never add a dependency or touch the frozen ABI to move a number.
- Re-measure with the FULL scorecard (not
--no-toolchain) before claiming a drop, anddos commit-audityour commit before claiming it shipped.
When to run this
- To baseline code quality (first run records score + code-debt).
- To drive the code-2x program — one halving per focused pass.
- After a burst of new
cmd/*tools or benchmarks (they land untested →testsdebt spikes; this pass retires it genuinely). - On a
/loopcadence to keep the kernel from rotting between releases.
The scorecard is read-only; this skill's only writes are your genuine fixes,
docs/CODE-QUALITY-SCORECARD.md, and the tool itself. It never edits the frozen
ABI and never games a SOFT KPI.
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.

