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

negframe-score

Skill49 starsChanged 14 days agoApache-2.0View on GitHub

One repeatable pass that keeps agent-steer prose leading with the AFFORDANCE, not the prohibition. Runs `fak score negframe` over the steer-prose corpus (AGENTS.md, CLAUDE.md, the skills, or explicit paths), reads the negframe_debt (mechanical negatives with an unambiguous positive rewrite) plus the judgement-tier soft signal, retires the mechanical debt worst-first by applying the suggested reframe, checks the `--since <ref>` ratchet before landing a steer-prose change, re-measures to PROVE the debt dropped, and commits only the scorecard lane by explicit path. Use. Use when this named workflow matches the task.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every finding lands in exactly one tier - do not conflate them:

    line 31
  2. Very specific:

    Default scope is the steer-prose corpus (negframe.ResolveTargets: AGENTS.md, CLAUDE.md, the skills).

    line 56
  3. Distinctive:

    Leave a genuinely load-bearing prohibition alone if reframing it would blur the boundary it exists to draw - this tier is a nudge, not a …

    line 67
  4. Very specific:

    After editing AGENTS.md, CLAUDE.md, or a skill's SKILL.md - run --since before landing to make sure the change did not introduce a new …

    line 119
  5. Very specific:

    After adding a new skill or a new refusal/guard message - scope negframe at the new file directly (go run ./cmd/fak score negframe …

    line 121

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

/negframe-score - lead with the affordance, not the prohibition

An instance of the generic scorecard doctrine. Read that for the five laws and the RSI loop; this file is the per-surface specialization.

Why this scorecard exists

Prose that steers an agent lands better when it leads with the ACTION to take instead of the thing to avoid. A reminder framed as an omission to fix ("remember: the commit stamp often gets skipped") makes the reader build a negative and invert it; "remember to stamp the commit" is the instruction already in the form the reader acts on. Across a whole steer-prose corpus - the guard runtime prose injected into every session, AGENTS.md, CLAUDE.md, the skills, the refusal vocabulary - that inversion tax compounds. internal/negframe is a TEXT-READING card: the prose on disk IS the data, so a finding can only be retired by reframing the sentence, never by editing a JSON file.

The two tiers (read this before touching anything)

Every finding lands in exactly one tier - do not conflate them:

  • MECHANICAL (HARD, gates negframe_debt) - the finding matches a fixed idiom with an unambiguous positive rewrite (a "forget-to-remember-to" idiom, or a double negative like "not un-<adjective>" that collapses to the plain adjective). The card hands back the exact Suggest string; apply it verbatim or a close paraphrase that preserves the meaning. This is the only tier that counts as debt.
  • JUDGEMENT (SOFT, advisory only) - negatively framed (a bare "never merge without review", "not allowed") but with no confident mechanical rewrite. The card names the Category (prohibition / absence / refusal / hedge) and a one-line Hint - the positive SHAPE to aim for - but never a literal reframe, and it never gates. Fix the cheap real ones by hand; do not chase this tier to zero, and never invent a mechanical rule just to move a soft count (see anti-gaming below).

The pass (the shared five-step loop)

  1. Run it - from the repo root:

    go run ./cmd/fak score negframe                 # human scorecard: debt + per-KPI
    go run ./cmd/fak score negframe --json           # machine payload (Corpus.negframe_debt / grade)
    go run ./cmd/fak score negframe --per-doc         # per-document finding breakdown (mechanical + judgement)
    go run ./cmd/fak score negframe --suggest         # review-diff view: every mechanical finding with its reframe

    Default scope is the steer-prose corpus (negframe.ResolveTargets: AGENTS.md, CLAUDE.md, the skills); pass explicit paths as positional args to score anything else. --per-doc also takes --json for a machine-readable finding list; --suggest prints text only.

  2. Retire negframe_debt worst-first - for every mechanical finding --suggest lists, apply the printed reframe to the source prose. This pass changes ONLY the flagged clause's wording - never the meaning, a claim, a number, or a link the sentence carries.
  3. Weigh the judgement (SOFT) findings, then stop - --per-doc shows each judgement finding's Hint. Reframe the cheap, obviously-better ones by hand (state the permitted path before the boundary; assert a property directly instead of by double negative). Leave a genuinely load-bearing prohibition alone if reframing it would blur the boundary it exists to draw - this tier is a nudge, not a work-list to drain.
  4. Check the diff-scoped ratchet before landing a steer-prose change:

    go run ./cmd/fak score negframe --since HEAD      # or the branch point / PR base ref

    This reports only negatives your CHANGE introduced (exit 1 if any new mechanical one appears) - a file absent at <ref> is treated as wholly new. This is the CI gate shape; run it locally before committing so you never introduce a new mechanical negative in the same diff that is supposed to be reducing them.

  5. Re-measure + prove, then commit only the scorecard lane, by explicit path:

    go run ./cmd/fak score negframe --json > /tmp/after.json
    go run ./cmd/fak score negframe --compare /tmp/before.json     # prints the debt delta
    go run ./cmd/fak score negframe --markdown > docs/NEGFRAME-SCORECARD.md
    fak sync reconcile --apply
    fak commit --path <reframe-files> --path docs/NEGFRAME-SCORECARD.md -m "style(negframe): reframe prose (fak negframe)"
    fak sync push

    State the delta plainly: negframe_debt N -> N' (-k). Commit the prose files you reframed together with the regenerated snapshot (if any); never git add -A. Push via fak sync push. End the subject with a (fak negframe) (or the touched leaf's) trailer so dos commit-audit binds it.

Reading the payload

Corpus carries negframe_debt (the mechanical count - the debt), documents (how many files were scanned), mechanical_debt, and judgement_soft. Schema is fak-negframe-scorecard/1. DebtKey is "negframe_debt" - the same string internal/scorecardpane folds into the portfolio total under the negframe card.

The anti-gaming rule (specific to this surface)

Fix a negative by reframing the sentence to genuinely lead with the action, never by deleting the directive or muting the detector. A mechanical finding is retired by applying its Suggest (or an equivalent positive rewrite), not by rewording it into a shape the lexicon happens not to match. Never widen a mechanical reframeRule's pattern just to make a finding disappear - the existing rules are deliberately high-precision (see the not un- allowlist in internal/negframe/negframe.go) precisely so a mechanical rewrite can never be wrong; loosening one to chase debt risks emitting a garbled "reframe" on prose it should not have matched. If a genuinely equivalent phrasing is already positive but still flags, the fix is to teach the lexicon that shape - recognizing real positive framing the rules were blind to is not weakening the check; suppressing a real negative is.

When to use this

  • After editing AGENTS.md, CLAUDE.md, or a skill's SKILL.md - run --since before landing to make sure the change did not introduce a new mechanical negative.
  • After adding a new skill or a new refusal/guard message - scope negframe at the new file directly (go run ./cmd/fak score negframe path/to/new/doc.md) before it joins the corpus.
  • On a /loop cadence to keep negframe_debt at zero as the steer-prose corpus grows.

The scorecard is read-only; this skill's only writes are the reframed prose, the regenerated docs/NEGFRAME-SCORECARD.md snapshot, and internal/negframe itself when a real lexicon gap is found (never a loosened one).

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.