agentleFS
anthony-chaudharyanthony-chaudhary/fak/.agents/skills/operator-heaviness-score/SKILL.md

operator-heaviness-score

Skill49 starsChanged 14 days agoApache-2.0View on GitHub

One repeatable pass that keeps fak light to DRIVE — the operator-facing counterpart of steerability-score. Runs the operator-heaviness scorecard (`fak operator heaviness`) over the live operator surface (the cmd/fak dispatch table, the front-door verb's flag set, the dos.toml refusal vocabulary, and whether the doc map makes the steering surfaces discoverable), reads the unbounded `heaviness_pressure` headline plus the HARD `heaviness_debt` gate, drives pressure DOWN and HARD debt to zero by REAL surface consolidation (group verbs, cut front-door flags, fold refusal reasons. Use when this named workflow matches the task.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 1 is distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read corpus.heaviness_pressure, corpus.heaviness_debt, and corpus.pressure_by_term (the per-KPI headroom consumed — the drift work-list, …

    line 72
  2. Very specific:

    If heaviness_debt > 0, retire the HARD defect first — it is the only thing that reds the control-pane ratchet.

    line 88
  3. Very specific:

    cli_verb_count / meta_verb_share (surface, SOFT): Every new top-level verb is one more thing an operator must discover.

    line 99
  4. Distinctive:

    NEVER remove a flag that gates a real guard.

    line 108
  5. Very specific:

    refusal_vocab_size (ceremony, SOFT): Every [reasons.*] block is one more token an operator must learn.

    line 109
  6. Very specific:

    Re-measure and dos commit-audit your commit: before claiming the pressure fell.

    line 191
  7. Very specific:

    After the dispatch table grows a verb, fak guard gains a flag, or dos.toml adds a refusal reason — the three events that move the pressure.

    line 196
  8. Very specific:

    When the top-level verb list feels like a navigation wall — cli_verb_count names the cliff and grouping is the move.

    line 198
  9. Very specific:

    When a guard refusal has no in-product appeal — appeal_channel_wired is the HARD defect that reds the ratchet.

    line 200

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

/operator-heaviness-score — keep the surface an operator drives flat as the repo grows

What this does. Steerability-score grades the SHAPE of the package graph — how hard the CODE is to change. No sibling answers the question an OPERATOR asks: as fak doubles in verbs and flags, does the effort to discover, drive, and recover the surface stay roughly flat, and if it drifts do we know and can we correct? This is that pass. It is an instance of the shared scorecard doctrine, pointed at the surface a person (or agent) actually DRIVES.

The shape: run the scorecard → read the pressure + the worst magnitude KPI → drive pressure DOWN with a REAL consolidation → re-measure and prove the pressure fell → regenerate the snapshot → commit ONLY your lane by explicit path.

The headline is heaviness_pressure — an unbounded integer that sums, per magnitude KPI, the share of headroom consumed between the comfortable soft line and the blowout ceiling (each term normalized to its own span so a verb and a flag are commensurable). Lower is lighter. It is deliberately NOT a 0–100 grade: a grade would flatten the one fact that matters — how far over the comfortable lines the surface sits today. heaviness_debt is the HARD gate, ~0 on a disciplined tree.


The measure (six KPIs, four groups, read from the live surface)

fak operator heaviness reads the operator-facing surface straight from the source — the cmd/fak dispatch table, the front-door verb's flag set, the dos.toml refusal vocabulary, and the llms.txt doc map — so it cannot be gamed by editing a JSON data file, only by genuinely slimming the surface. Two KPIs emit HARD debt; four are SOFT magnitudes that score the pressure but never emit debt (because their only cheap "fix" would be deleting a real guard, which is not a fix).

GroupKPIHARD/SOFTwhat it measures (the operator load)
discoverabilitydocmap_covers_steeringHARDevery steering surface is reachable from a linked doc-map entry (not a bare mention)
recoveryappeal_channel_wiredHARDthe dispatch table routes an in-product appeal verb (fak complain) for a wrong refusal
surfacecli_verb_countSOFT, HARD past 200top-level subcommands an operator must hold (soft 90, blowout ceiling 200)
surfacemeta_verb_shareSOFTshare of verbs that are meta-scorecards/RSI clutter (soft 8%, ref 25%)
configfront_door_flag_burdenSOFT, HARD past 80flags on the front-door verb fak guard (soft 20, blowout ceiling 80)
ceremonyrefusal_vocab_sizeSOFTstructured refusal reasons an operator must learn (soft 12, ref 30)

Why only two HARD KPIs. Both have a genuine, non-gaming fix: a steering surface the doc map hides is fixed by writing a real linked doc-map entry; a missing appeal channel is fixed by wiring the verb. The four magnitude KPIs are SOFT because their cheapest "fix" — deleting a verb, a flag, or a refusal reason — would delete a real capability or guard. They score the pressure (so an operator sees the load climbing) and turn HARD only at the blowout ceiling (verb count > 200, flag count > 80), where the fix is a genuine consolidation program, not a tweak.


Step 1 — Run the scorecard (it builds your work-list)

From the repo root:

fak operator heaviness                 # human scorecard (pressure + per-KPI + verdict)
fak operator heaviness --json          # machine payload (the loop uses this)

Read corpus.heaviness_pressure, corpus.heaviness_debt, and corpus.pressure_by_term (the per-KPI headroom consumed — the drift work-list, where the load concentrates). If heaviness_debt > 0, a HARD defect is live and that is the first thing to retire.

Record the baseline before you change anything so you can prove the delta:

fak operator heaviness --json > heaviness-baseline.json   # local, per-pass; not committed

(This is a per-pass local anchor like steerability-score's baseline.json — the pressure moves as verbs/flags land, so a fixed committed anchor goes stale immediately; regenerate it each pass and point --compare at it.)

Step 2 — Drive pressure DOWN, HARD debt to zero, using REAL consolidation only

If heaviness_debt > 0, retire the HARD defect first — it is the only thing that reds the control-pane ratchet. Then attack the largest pressure_by_term. The genuine moves, by KPI:

  • docmap_covers_steering (HARD, discoverability). A steering surface (steerability, operator-heaviness) is not reachable from a linked doc-map entry. Fix it by adding a real llms.txt line that links to the surface's doc (e.g. - [Operator-heaviness scorecard](../../../docs/OPERATOR-HEAVINESS.md): ...). A bare prose mention with no markdown link does NOT retire the gate — the oracle requires the link shape.
  • appeal_channel_wired (HARD, recovery). The dispatch table has no in-product appeal verb for a wrong refusal. Fix it by wiring fak complain (the internal/guardcomplaint channel) into the dispatch table — a real recovery seam, never a stub case that exits 0.
  • cli_verb_count / meta_verb_share (surface, SOFT). Every new top-level verb is one more thing an operator must discover; meta-scorecard/RSI verbs clutter without adding product capability. Drive pressure down by grouping verbs under a parent (fak operator ..., fak guard-rsi ...) so the top-level table shrinks — real consolidation, the same move that keeps a dispatch file steerable. NEVER delete a verb that has users to move the count.
  • front_door_flag_burden (config, SOFT). fak guard carrying 60+ flags is its own steerability tax. Drive pressure down by graduating a stable cluster of flags into a subcommand or a policy-profile preset (--policy examples/...) so the front door shrinks. NEVER remove a flag that gates a real guard.
  • refusal_vocab_size (ceremony, SOFT). Every [reasons.*] block is one more token an operator must learn. Drive pressure down only by folding two reasons that name the same recovery into one canonical token. NEVER delete a reason the kernel actually emits — that hides a real refusal from the closed vocabulary.

heaviness_pressure is advisory by design: a clean pass HOLDS it flat (no verbs/flags added), a consolidation pass drives it DOWN. It is not a gate — do not chase a lower number by deleting real surface.

Step 3 — Validate every surface change (the honesty gate)

Any dispatch-table, flag, or doc-map edit must keep behavior identical and the build green. Native go test is OS-blocked on the Windows dev box, so validate under WSL:

go build -o "$TEMP/fak-verify.exe" ./cmd/fak          # compiles (never write the in-tree binary)
go vet ./cmd/fak ./internal/heavinessscore/...
wsl -e bash -lc 'cd /mnt/c/work/fak && go test ./internal/heavinessscore/... -count=1'

A surface edit you have not built and tested is not done. Never add a stub verb/flag/reason solely to move a number.

Step 4 — Re-measure and PROVE the pressure fell

fak operator heaviness --json
fak operator heaviness --compare heaviness-baseline.json   # the pressure/debt delta + verdict

State the delta plainly: pressure P → P' (−k), the KPI that moved, and whether heaviness_debt reached 0. Regenerate the committed snapshot so the public doc tracks the surface:

fak operator heaviness --markdown > docs/OPERATOR-HEAVINESS.md   # use Bash '>'; PowerShell mangles glyphs

Step 5 — Commit ONLY your lane, by explicit path

The scorecard reads five files across three lanes (cmd, tools, docs/claude). Commit each lane's files in their OWN commit by explicit path via fak commit --path — never git add -A:

fak sync reconcile --apply
fak commit --path cmd/fak/<changed>.go -F msg                    # the surface edit (cmd lane)
fak commit --path docs/OPERATOR-HEAVINESS.md --path llms.txt -F msg     # the snapshot + doc-map (docs lane)
dos commit-audit HEAD                                            # MUST print [diff-witnessed] / verdict OK
fak sync push

Subject honesty: a real surface consolidation → refactor(cmd):; a doc-map/snapshot regeneration → docs(steer): or chore(steer):. End every ship commit with a (fak <leaf>) trailer matching the lane you touched so the dos verify referee binds it. Stay on main; never force-push.


The RSI loop

Each pass: measure → retire HARD debt, then drive the largest pressure_by_term down → prove the pressure fell → commit witnessed. Next pass, the new largest term surfaces — the loop walks the operator surface lighter because the pressure is re-derived from the live dispatch table every time and can't be talked past. Because the soft lines sit below today's surface on purpose, a clean pass holds pressure flat (no new surface added), which is the whole goal: the same driving effort at 2× the verbs.

Anti-gaming laws (the pressure is only as honest as the pass)

  1. Never delete a verb, flag, or refusal reason to move a count. The SOFT magnitude KPIs are SOFT for exactly this reason — deleting a real capability or guard is not consolidation. Group, graduate, or fold instead.
  2. Never satisfy docmap_covers_steering with a bare prose mention. The oracle requires a linked doc-map entry (a markdown link on the same line as the token). Pasting the token into a sentence games the gate without aiding discovery.
  3. Never wire a stub fak complain case that exits 0. appeal_channel_wired requires a real recovery seam (internal/guardcomplaint); a stub hides a wrong refusal with no appeal.
  4. Never re-derive a code-shape number here. Steerability-score owns the package graph; this card owns the operator surface. Double-counting the same monolith is the orthogonality bug this split exists to prevent.
  5. Never commit a fixed pressure "baseline" data file. The pressure moves as the surface lands; a committed anchor goes stale immediately and misleads the next --compare. Regenerate the local per-pass anchor each time (steerability-score's convention).
  6. Re-measure and dos commit-audit your commit before claiming the pressure fell.

When to run this

  • To baseline operator-heaviness (first run records the pressure + the worst magnitude KPI).
  • After the dispatch table grows a verb, fak guard gains a flag, or dos.toml adds a refusal reason — the three events that move the pressure.
  • When the top-level verb list feels like a navigation wall — cli_verb_count names the cliff and grouping is the move.
  • When a guard refusal has no in-product appeal — appeal_channel_wired is the HARD defect that reds the ratchet.
  • On a /loop cadence to keep the driving surface flat as the repo grows between releases.

The scorecard is read-only; this skill's only writes are your genuine surface consolidations, docs/OPERATOR-HEAVINESS.md, and llms.txt. It never deletes a real guard to move a number and never edits the frozen ABI.

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.