decision-making-skills
CLAUDE.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
In this repository28 other files it gives its agents.
- AGENTS.mdAGENTS.md
- academic-paper-reviewSkill
- citation-managementSkill
- decision-makingSkill
- experimental-designSkill
- hypothesis-generationSkill
- paper-lookupSkill
- peer-reviewSkill
- read-arxiv-paperSkill
- scientific-critical-thinkingSkill
- scientific-writingSkill
- statistical-analysisSkill
- statistical-powerSkill
- systematic-literature-reviewSkill
- venue-templatesSkill
- academic-paper-reviewSkill
- citation-managementSkill
- experimental-designSkill
- hypothesis-generationSkill
- paper-lookupSkill
- peer-reviewSkill
- read-arxiv-paperSkill
- scientific-critical-thinkingSkill
- scientific-writingSkill
- statistical-analysisSkill
- statistical-powerSkill
- systematic-literature-reviewSkill
- venue-templatesSkill
The file
We split this CLAUDE.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
- Very specific: line 5
Read by Codex, Cursor, Copilot, Gemini CLI, Cline, Amp, OpenCode and others.
- Very specific: line 9
Every rule below exists because the failure it prevents already happened here.
- Very specific: line 38
Do not reword that block. It is the install artefact and the measured wording.
- Distinctive: line 77
Never drop a model tier, trim a stratum or cut repeats to save money.
- Very specific: line 87
Read docs/AUTONOMOUS_WORK_ORDER.md first.
- Distinctive: line 114
Never run a recursive delete or a forced clean at the repository root.
- Very specific: line 134
Never git push origin <topic>:main, which moves the remote and leaves local main where it was.
- Distinctive: line 155
Run continuously. Quota is not a reason to hold back: state a run's call count, then start it.
- Distinctive: line 291
Write down what will be computed, from which records, over which denominator, by which function.
- Distinctive: line 298
Check that some possible response would have scored above zero for this arm, and that the scorer reads the same object in every arm.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.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.
Files
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 fetchNever 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 landedNever 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/mainThe 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.pyuv 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 mirrorfirst if you touchedAGENTS.mdorskills/, becauseCLAUDE.mdis itself a site input. Thenpython -m uv run de sync, thenpython -m uv run de site.de checkrefuses a stalesite/build-manifest.jsonand names the files that moved. Merging tomaindeploys;python -m uv run de deployedsays whether it landed, and exit 2 means it could not tell. - A published run carries its own provenance.
results/<skill>/<date>-<sha7>[-slug]/README.mddeclares**Answer key:** <label set> v<n>matching theset_versionin the records beside it, and aPrediction:line naming a notebook entry whose first commit is an ancestor of the run's commit. Two pre-convention runs are baselined inresults/provenance-baseline.txt; that list may only shrink. Regeneratedocs/RUN_INDEX.mdwithde index. - An answer key on disk has been through blind adjudication.
de checkrefuses a trigger set carrying an item with no three-judge record inresults/triggers/adjudication.jsonl, so authoring items and adjudicating them is one unit of work. Close it withpython -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 indatasets/triggers/adjudication-baseline.txt; that list may only shrink. - A published run updates
docs/STATUS.mdin the same change. Corrections there are appended, never rewritten. - A change to
datasets/triggers/,datasets/tailoring/,skills/orevals/src/decision_evals/arenas.pyneeds an entry indocs/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.mdanddocs/for drift and land the sweep as a datednotebook/entry. Count runs fromdocs/RUN_INDEX.md, which is generated and cannot itself drift. - Run
python -m uv run de driftfor the worklist. It names the documents whose files have moved since anyone recorded reading them, furthest behind first. Read those, re-readdocs/README.mdas an index, and record each in[tool.decision-evals.reviewed]at the commit you read it at.de checkrefuses 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
desubcommand, a step of the gate, a module of the harness, a file of the skill, an arm: mark the region andpython -m uv run de syncwrites it. A figure registered insite/claims.jsongoes in ade:factmarker, 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 isdocs/DOCUMENTATION_MAP.md. - A coverage floor does not mean a module runs.
de checkrefuses 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 regionscatches a table that is not what it renders from, andpublished claimscatches a figure that no longer matches its source. Scope for all three is root*.mdanddocs/recursively.notebook/,results/**/README.md,docs/DECISIONS.mdanddocs/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.mdis the index and the site's/docs/page;de checkcompares it againstdocs/in both directions, refuses a living document carrying no**Audience:**line, and refuses one under adocs/subdirectory that nothing links to. Where a document goes and which class it belongs to isdocs/DOCUMENTATION_MAP.md; splitting one goes by exact line boundaries, never by rewrapping. - All prose you write goes through
docs/VOICE.mdand the humanizer skill, including the comments and docstrings you touch. Review withdocs/reviews/HOUSE_STYLE.mdanddocs/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.bibentry 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.
- Change a number, a confidence interval, a p-value, an arXiv identifier or
a quoted sentence. The rule that a
skills/decision-making/SKILL.md's description is the measured artefact.scripts/run_triggers.pyreads that field and nothing else, so rewriting it makes every published number incomparable. It changes only as a deliberate new arm with an entry indocs/DECISIONS.md.- Commits are attributed to the GitHub noreply address.
de checkenforces a narrower rule than that: it refuses an unsetuser.nameoruser.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 --blessand 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 indatasets/triggers/decision-making/index.yamlbefore 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).
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.

