agentleFS
AngelCampa1AngelCampa1/decision-making-skills/AGENTS.md

decision-making-skills

AGENTS.md1 starsChanged 3 months agoApache-2.0View on GitHub

Audience: an agent working in this repository. Read by Codex, Cursor, Copilot, Gemini CLI, Cline, Amp, OpenCode and others. Claude Code reads CLAUDE.md, a byte-exact mirror written by de mirror. Edit this file only. de check refuses a stale mirror. Every rule below exists because the failure it prevents already happened here. The dated incidents, the measurements and the citations behind them are in docs/WHY_THESE_RULES.md, which nothing loads per turn. Read a section there when you want to know why…

  • Commits and pushes

The file

We split this AGENTS.md into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    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
  1. Very specific:

    Read by Codex, Cursor, Copilot, Gemini CLI, Cline, Amp, OpenCode and others.

    line 5
  2. Very specific:

    Every rule below exists because the failure it prevents already happened here.

    line 9
  3. Very specific:

    Do not reword that block. It is the install artefact and the measured wording.

    line 38
  4. Distinctive:

    Never drop a model tier, trim a stratum or cut repeats to save money.

    line 77
  5. Very specific:

    Read docs/AUTONOMOUS_WORK_ORDER.md first.

    line 87
  6. Distinctive:

    Never run a recursive delete or a forced clean at the repository root.

    line 114
  7. Very specific:

    Never git push origin <topic>:main, which moves the remote and leaves local main where it was.

    line 134
  8. Distinctive:

    Run continuously. Quota is not a reason to hold back: state a run's call count, then start it.

    line 155
  9. Distinctive:

    Write down what will be computed, from which records, over which denominator, by which function.

    line 291
  10. Distinctive:

    Check that some possible response would have scored above zero for this arm, and that the scorer reads the same object in every arm.

    line 298

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md 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
AGENTS.md

Agent instructions

Audience: an agent working in this repository.

Read by Codex, Cursor, Copilot, Gemini CLI, Cline, Amp, OpenCode and others. Claude Code reads CLAUDE.md, a byte-exact mirror written by de mirror. Edit this file only. de check refuses a stale mirror.

Every rule below exists because the failure it prevents already happened here. The dated incidents, the measurements and the citations behind them are in docs/WHY_THESE_RULES.md, which nothing loads per turn. Read a section there when you want to know why a rule is worded the way it is.

Copy this into your project's AGENTS.md or CLAUDE.md

## Decision skills

- **decision-making** — when someone is trying to decide something and wants help
  deciding it: "help me think this through", "should I take it", "what would you
  do", or a pile of context ending in a question about what to do. It routes to
  one of six procedures depending on what is actually hard — too much context,
  advice that may not fit this person, downstream consequences, timing, several
  positions that are each defensible, or a missing fact that may or may not
  matter — and reads only that one. Skip it for lookups, for creative or exploratory work, and
  when the person wants information rather than a recommendation.

One entry, not four. Four separate decision skills would have four descriptions
that all read as "help me decide", and overlapping descriptions are the
mechanism by which agents pick the wrong skill.

Trust your own read on when it applies. It is a procedure, not a policy: if it
is producing worse answers than thinking directly, that is worth knowing and
worth saying.

Do not reword that block. It is the install artefact and the measured wording. Why it is one entry: docs/WHY_THESE_RULES.md.

Installing the skills

# Cross-tool: Codex, Cursor, Copilot, Gemini CLI, Cline, Amp, OpenCode
cp -r .agents/skills/* ~/.agents/skills/

# Claude Code, project-scoped
cp -r skills/* .claude/skills/

Canonical skills carry only the six portable frontmatter fields of the Agent Skills standard. Vendor-only keys (context: fork, disable-model-invocation) are a hard error in most of those tools and live in the plugin overlay.

What is proven

Nothing yet. decision-making and all six procedures carry verdict: UNTESTED and ship as experimental. A verdict governs the public claim and says nothing about whether the skill is usable. See SCORECARD.md.

Cost

Three venues carry model calls: the Claude Code CLI on a Claude Max subscription, a local OpenAI-compatible server, and a free-tier API endpoint. A key for a free tier is permitted, lives in the environment and never in the tree. Every call goes through the checkpointed runner whatever the venue, so which one answered stays in the record. Maintainer instruction, 2026-08-26; the reasoning is in docs/WHY_THESE_RULES.md.

total_cost_usd is a notional API-equivalent price: a burn meter, never an expense and never a spend cap. Report it as notional cost. It reads zero on a local model and on a free tier, so a run there is guarded by call count and wall clock instead, and a dollar cap that cannot fire is worth nothing.

Never drop a model tier, trim a stratum or cut repeats to save money. The budget is the rolling quota, a free tier's rate limit, and wall-clock time, which is why the runner is checkpointed and resumable. Nothing may be bought: no paid APIs, datasets or tooling. "Vendoring" means checking a copy into datasets/vendor/.


Working in this repository

Read docs/AUTONOMOUS_WORK_ORDER.md first. It carries the five standing rules, the sub-agent and adversarial-review method, where a worktree goes and what it needs, and the ordered landing sequence. What follows is a summary of it, not a replacement.

Other sessions

Several run here at once. Files you did not write, commits you did not author and a tree dirty in places you never touched belong to another session. Do not stop, do not narrate them, do not kill their processes. Prefer Edit over Write on files you did not create this session, re-read before editing, stage only your own paths, and speak up only on a real conflict. Never git stash in a shared tree: git show HEAD:<path> and git diff -- <path> answer the same question without touching anyone else's work.

Worktrees

Any session running longer than a few minutes gets its own tree, its own .venv, its own gate.

git worktree add -b <topic> .claude/worktrees/<topic> origin/main
cd .claude/worktrees/<topic>
python -m uv sync --group dev
python -m uv run de fetch

Never run a recursive delete or a forced clean at the repository root. Other sessions' worktrees sit in that blast radius.

Rejoin at least daily and at least every ten commits, and push even when the work is unfinished:

git fetch origin && git rebase origin/main && git push -u origin <topic>

Land by merging from a green worktree. --no-verify is not how a red gate gets resolved. Commit, do not stage: a gate that runs in the working tree cannot see what the commit is missing. Then prove it landed:

git fetch origin
git rev-parse main origin/main                             # two identical lines
git merge-base --is-ancestor <your-topic-sha> origin/main  # exit 0 means landed

Never git push origin <topic>:main, which moves the remote and leaves local main where it was. Never git update-ref refs/heads/main, which bypasses the checked-out protection and leaves that worktree showing deletions nobody made. main is usually checked out somewhere, so read git worktree list first and fast-forward it in place:

git -C <the-worktree-holding-main> merge --ff-only origin/main

The full order, deploy confirmation and cleanup are in Landing the work.

Method

Dispatch units of work to sub-agents and run the independent ones concurrently. Give every artefact a different agent briefed to break it. Treat one agent's result as a hypothesis until an independent agent re-derives it from the raw records, the run reproduces, or the reviewer's specific objection is checked and fails. A "looks good" review has not run.

Run continuously. Quota is not a reason to hold back: state a run's call count, then start it.

The gate

uv sync --group dev
python -m uv run de check              # the full local gate
python -m uv run de check --fast       # pre-commit subset: no tests, coverage, site or drift
python -m uv run pytest tests/unit/test_claims.py

uv is not on PATH here, hence python -m uv. Run the full gate before believing anything works. It also runs in CI (.github/workflows/check.yml) on a clean checkout, which sees what a working directory cannot. A second workflow, deploy-site.yml, publishes the site and checks nothing.

Where the code is

evals/src/decision_evals/ is the harness and the gates. gate_steps() in cli.py is the whole of de check, in order, and each step lives in the module it is named after: docs.py, citations.py, provenance.py, decisions.py, wiring.py, skills.py, sync.py, drift.py, claims.py, site.py, adjudication.py, corrections.py, rescore.py. scripts/run_triggers.py is the runner behind every checkpointed model call on record. Track H's probes go through sub-agents instead, which is why they carry no checkpoint, no total_cost_usd and nothing for SCORECARD.md. datasets/ is the answer key, skills/ the product, results/ and notebook/ the record. docs/ARCHITECTURE.md draws how they fit and how a run flows through them. README.md carries the component table and docs/RESEARCH_PROGRAMME.md maps the tracks to docs/programme/.

Standing obligations

  • Editing a document means rebuilding the site in the same change. Run python -m uv run de mirror first if you touched AGENTS.md or skills/, because CLAUDE.md is itself a site input. Then python -m uv run de sync, then python -m uv run de site. de check refuses a stale site/build-manifest.json and names the files that moved. Merging to main deploys; python -m uv run de deployed says whether it landed, and exit 2 means it could not tell.
  • A published run carries its own provenance. results/<skill>/<date>-<sha7>[-slug]/README.md declares **Answer key:** <label set> v<n> matching the set_version in the records beside it, and a Prediction: line naming a notebook entry whose first commit is an ancestor of the run's commit. Two pre-convention runs are baselined in results/provenance-baseline.txt; that list may only shrink. Regenerate docs/RUN_INDEX.md with de index.
  • An answer key on disk has been through blind adjudication. de check refuses a trigger set carrying an item with no three-judge record in results/triggers/adjudication.jsonl, so authoring items and adjudicating them is one unit of work. Close it with python -m uv run python scripts/adjudicate.py --set <the set> --missing-only, and read the outcome against the pre-registered kill at more than 20% of labels moving. The version 2 corpus is baselined in datasets/triggers/adjudication-baseline.txt; that list may only shrink.
  • A published run updates docs/STATUS.md in the same change. Corrections there are appended, never rewritten.
  • A change to datasets/triggers/, datasets/tailoring/, skills/ or evals/src/decision_evals/arenas.py needs an entry in docs/DECISIONS.md. Commit bodies are not the store. The first three are the answer keys and the product; the fourth is the model registry, which decides which runs may become evidence.
  • Every third published run, sweep README.md and docs/ for drift and land the sweep as a dated notebook/ entry. Count runs from docs/RUN_INDEX.md, which is generated and cannot itself drift.
  • Run python -m uv run de drift for the worklist. It names the documents whose files have moved since anyone recorded reading them, furthest behind first. Read those, re-read docs/README.md as an index, and record each in [tool.decision-evals.reviewed] at the commit you read it at. de check refuses a document with no review or one more than ten commits past it.
  • A document does not type out what the repository already knows. A de subcommand, a step of the gate, a module of the harness, a file of the skill, an arm: mark the region and python -m uv run de sync writes it. A figure registered in site/claims.json goes in a de:fact marker, and the number itself stays in the register. Both markers are HTML comments and invisible wherever the document renders. Where they go and what refuses them is docs/DOCUMENTATION_MAP.md.
  • A coverage floor does not mean a module runs. de check refuses a floored module that no entry point can reach. Intentional gaps go in [tool.decision-evals.unwired] with the condition that would close them.
  • No gate reads whether a description is true. The documentation gate catches a reference that does not resolve, generated regions catches a table that is not what it renders from, and published claims catches a figure that no longer matches its source. Scope for all three is root *.md and docs/ recursively. notebook/, results/**/README.md, docs/DECISIONS.md and docs/superpowers/plans/ are excluded as dated records, so do not "fix" a stale reference in them. Deliberately absent commands go in [tool.decision-evals.docs-absent-commands] and deliberately untracked paths in [tool.decision-evals.docs-ignored-paths]. Both may only shrink, and both refuse an entry named nowhere in the scanned documentation. Prose describing a mechanism names the arena and the tense it runs in: a gate scoped to an arena that has never run will refuse, it does not refuse.
  • A new document is listed, declares an audience, and is reachable. docs/README.md is the index and the site's /docs/ page; de check compares it against docs/ in both directions, refuses a living document carrying no **Audience:** line, and refuses one under a docs/ subdirectory that nothing links to. Where a document goes and which class it belongs to is docs/DOCUMENTATION_MAP.md; splitting one goes by exact line boundaries, never by rewrapping.
  • All prose you write goes through docs/VOICE.md and the humanizer skill, including the comments and docstrings you touch. Review with docs/reviews/HOUSE_STYLE.md and docs/reviews/POSITIONING.md. Nothing checks this. It applies going forward and never retroactively: bring a comment up to standard when you change it, and do not sweep the source for style. Three things the pass may never do:
    • Change a number, a confidence interval, a p-value, an arXiv identifier or a quoted sentence. The rule that a paper/refs.bib entry must carry a quote before a number may be asserted beside it is scoped to the markdown block, so rewrapping alone can move a claim number into a block whose identifier has no quote behind it and turn a green gate red.
    • Delete a correction that a register depends on. Nothing stops you.
    • Flatten a hedge that carries epistemic status. Collapse stacked hedges and leave the load-bearing one.
  • skills/decision-making/SKILL.md's description is the measured artefact. scripts/run_triggers.py reads that field and nothing else, so rewriting it makes every published number incomparable. It changes only as a deliberate new arm with an entry in docs/DECISIONS.md.
  • Commits are attributed to the GitHub noreply address. de check enforces a narrower rule than that: it refuses an unset user.name or user.email, and an email under the maintainer's employer domain. It is a blocklist of one.
  • Golden files pin the generated corpus byte-exact. Regenerating them needs pytest --bless and the diff belongs in review.
  • notebook/ is append-only and dated. Predictions go in before runs, and a prediction that turned out wrong stays and says so.

Before any run

  • Write down what will be computed, from which records, over which denominator, by which function. If that sentence cannot be written, the run is not ready. A registered band names its estimator and its denominator, not just its number.
  • Set a recall band under the observed per-item ceiling, computed from the items you are about to run. Check the ancestry: block in datasets/triggers/decision-making/index.yaml before carrying a per-item fact across corpus versions.
  • Check that some possible response would have scored above zero for this arm, and that the scorer reads the same object in every arm.
  • Version the answer key, stamp the version into every record, and refuse comparisons across versions (trigger_arms.label_versions_comparable).

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.