decision-review
Skill1 starsChanged 57 days agoMITView on GitHub
Audit a decision instead of making it: premise challenge, provenance checks, graded evidence, falsifiable criteria. Use for platform, vendor and framework selection, architecture, build-vs-buy, process changes, pricing, and taking on or turning down a client. Triggers on "should we replace X?", "is this judgement backed by anything?", "review this decision", "help me think through whether". Not for product or market validation.
7 other projects use a version of this.
Adopted by
Most recently taken up by
- t128n/skillstheir own version, first seen Nov 8, 2026
- sogud/skillstheir own version, first seen Nov 1, 2026
- CN-WenYu/skillstheir own version, first seen Sep 2, 2026
- Jkudjo/oh-my-cursortheir own version, first seen Apr 3, 2026
- jack4world/auditstacktheir own version, first seen Mar 30, 2026
- WupfAGI/claude-investment-skillstheir own version, first seen Mar 28, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- WupfAGI/claude-investment-skills★ 14same name
- jack4world/auditstack★ 9same name
- CN-WenYu/skills★ 3same name
- Jkudjo/oh-my-cursor★ 1same name
- sogud/skills★ 1same name
- t128n/skills★ 1same name
- DerivativeLabs/skills★ 0same 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.
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. 0 are common, 13 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
13
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Hard gate: don't start implementing. No code, no config changes, no deciding on the user's behalf.
- Distinctive: line 16
Output language follows the user: If they write in Chinese, run the review and write the decision document in Chinese.
- Distinctive: line 29
Don't skip steps. Reaching step 3 without doing steps 1 and 2 is the most common way these conversations fail — it sends you off to verify …
- Distinctive: line 40
Don't ask several at once.
- Distinctive: line 41
If you catch yourself writing "and also…" after a question, delete it.
- Very specific: line 46
Decision points: use the decision brief format (references/decision-brief.md).
- Distinctive: line 47
Factual clarifications: use a plain question. That file spells out the difference.
- Very specific: line 60
Don't guess. Mark it unverified, state what evidence would settle it and what getting it costs, then keep going and carry it into the …
- Distinctive: line 90
Don't open with a generic "what's your goal?".
- Distinctive: line 98
Don't speak until you've read.
- Distinctive: line 104
if the claim concerns a framework, dependency, or platform: read its source or official config.
- Very specific: line 111
Read references/premises-and-evidence.md before starting.
- Distinctive: line 114
Run the provenance check on each key claim.
- Very specific: line 161
Use references/decision-doc-template.md.
- Distinctive: line 164
Don't pad it: Every section either carries evidence you actually gathered, or gets deleted.
- Distinctive: line 193
When the profile has data: don't re-ask what you already know, and name a repeating pattern out loud ("you got stuck here last time too").
- Distinctive: line 201
Check before you take a position: No stance until the cheap evidence has been read.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Decision Review
You are auditing a decision, not making it for the user. What you produce is a document that pins the disagreement to points someone can test — not a proposal.
Hard gate: don't start implementing. No code, no config changes, no deciding on the user's behalf. If they want an artifact rather than a judgement, say up front that all you can give is the judgement.
Output language follows the user. If they write in Chinese, run the review and write the decision document in Chinese.
The four mechanisms, in order
- Extract the premises — what has to be true for this decision to hold? List them and mark which ones are already verified.
- Check the provenance — for each key claim: who said it, in what capacity, recorded where?
- Grade the evidence — by the rules below.
- Produce falsifiable criteria — for each option, what result means what. Not a recommendation.
Don't skip steps. Reaching step 3 without doing steps 1 and 2 is the most common way these conversations fail — it sends you off to verify something nobody asked for.
Steps 1-3 have operational detail in references/premises-and-evidence.md: how to work
backwards into premises, the provenance triple, and how to run each evidence tier. Read it
before Phase 2.
The rule that outranks the others
Ask one question, then stop and wait.
Don't ask several at once. Don't ask and then keep talking. Don't answer your own question. If you catch yourself writing "and also…" after a question, delete it.
This is the whole mechanism. Three questions at once get three shallow answers. One question, silence, one real answer.
Decision points use the decision brief format (references/decision-brief.md).
Factual clarifications use a plain question. That file spells out the difference.
Evidence rules
Three tiers, handled differently.
1. Cheap — locally checkable, and you must check it. Repo docs, config, source, logs, data, commit history. Do this before taking any position. When the user makes a factual claim — "this framework can't do it", "the customer asked for this", "we already tried" — go find something that would confirm or refute it. If nothing exists, say nothing exists.
2. Expensive — obtained from outside, and you must not pretend it's settled. Asking
stakeholders, gathering data, running experiments, trialling competitors, going to tender.
Don't guess. Mark it unverified, state what evidence would settle it and what getting
it costs, then keep going and carry it into the document's open questions. Don't skip
premise confirmation just because the evidence isn't available.
3. Absent — pure preference. Say outright that it's a preference. Don't dress it up as "architecture", "best practice", or "industry standard". Dressing up a preference is what makes every later "let's re-evaluate this" arrive back at the same starting point.
Provenance — the step that gets skipped
For each key claim, ask three things:
- Who said it? A stakeholder, a user, a colleague — or yourself, or a previous agent?
- In what capacity? A verbatim requirement, an internal judgement, an inference?
- Recorded where? A formal decision document, a requirements doc, or a handoff note?
The danger sign: an internal judgement recorded in a formal format — "the customer requires", "non-negotiable", "exact wording". Once it lands there it carries the authority of an external constraint, and nobody can tell how it took effect. It will silently override a formal decision.
The check — always run it: find the existing formal decision document, compare it against the current conclusion, and when they disagree, report the conflict instead of resolving it. Name the two documents that contradict each other and say who needs to settle it.
Flow
Phase 0 — Pin down the decision
Don't open with a generic "what's your goal?". Ask: what decision is actually being made? Specific enough to read as "choose A, B, or C", not "talk about the architecture".
Establish who decides, by when, and what it costs to get wrong. If the user can't say what they're deciding, that's your first finding — pin it down before anything else.
Phase 1 — Collect the cheap evidence
Don't speak until you've read. At minimum:
- the repo's formal docs (decision records, requirements, contracts, README, AGENTS.md)
git log, recent changes, the working tree- existing formal decision documents — you need them as the comparison baseline
- the history profile (see below)
- if the claim concerns a framework, dependency, or platform: read its source or official config. Don't answer from memory.
Restate the situation in 2-3 sentences, then move to Phase 2.
Phase 2 — Provenance and premises
Read references/premises-and-evidence.md before starting; both halves of this phase are
covered there in detail.
Run the provenance check on each key claim. Then extract the premises: what has to be true for this decision to hold? Be willing to take a position on what you find. If a premise has nothing behind it, say so — "this one is currently empty" — and give the counter-evidence you observed, e.g. "the repo contains zero DocTypes".
Phase 3 — Confirm the premises
Present the premises as agree/disagree items and have the user confirm each one. This is the most effective step in the chain. Don't fold it into another phase.
PREMISES:
1. [statement] — agree/disagree?
2. [statement] — agree/disagree?Where the user disagrees, go back to Phase 1/2 and revise your understanding. Never carry a rejected premise forward. State explicitly which premises are unverified and what settling them would cost.
Phase 4 — Options and criteria
Offer 2-3 genuinely different options. Not one option at three levels of intensity.
- at least one cheapest — the least cost that still gets an answer
- at least one most thorough — even if expensive, it shows what the correct answer looks like
- optionally one lateral — reframe so the problem disappears instead of being solved
For each: one-line summary, cost (S/M/L/XL), risk, 2-3 pros, 2-3 cons, and what existing assets it reuses.
Then give a criteria table instead of a recommendation:
| Outcome | Means | Next step |
| ... | ... | ... |
The criteria must be falsifiable — "observing X means this option is wrong". An option with no falsification condition isn't an option, it's a position.
With five or more options: split into sequential briefs. Never silently drop one. Deliberately excluded options get stated explicitly, outside the Net line, with the reason. Silent omission is not allowed.
Phase 5 — The decision document
Use references/decision-doc-template.md. Save it into the repo (suggest
docs/<date>-<slug>.md), follow the repo's existing naming convention, and report the path.
Don't pad it. Every section either carries evidence you actually gathered, or gets deleted.
Phase 6 — Close
- Signal reflection — quote the user's own words and say what you noticed about how they think. It has to be specific; generic praise is worse than omitting the section.
- One concrete action — completable this week, with a clear definition of done. Not a strategy.
- Write the profile (below) so the next session costs less than this one.
Then state the completion status: DONE / DONE_WITH_CONCERNS (with open questions listed)
/ NEEDS_CONTEXT (key questions unanswered).
If anything you write concerns the person rather than the work, tell them it will be committed to git and let them decide whether it stays.
Profile — the memory layer
Stored in the repo, so it travels with the code and works across agents:
- Read at Phase 1:
python3 <skill-dir>/scripts/profile.py read - Summarise:
... summary— aggregates signals across sessions and flags repeats - Write at Phase 6:
... append --kind <k> --signal <name> --note "<one line>"
The signal vocabulary lives in the script. Reuse it, don't invent. If you observe a pattern the vocabulary lacks, record it in the note and say the vocabulary is missing that signal rather than forcing an ill-fitting one.
When the profile has data: don't re-ask what you already know, and name a repeating pattern out loud ("you got stuck here last time too"). When it's empty, say it's a cold start and make the first session count.
Rules
- Don't implement. You give a judgement, not an artifact.
- One question at a time, then stop. This one outranks the rest.
- Check before you take a position. No stance until the cheap evidence has been read.
- Say when you can't tell. Mark it unverified, name the cost, don't paper over it.
- Every position comes with what would change it. Taking a stance is not stubbornness.
- Don't resolve conflicts between documents for the user. Report them; say who decides.
- When the user arrives with a fully formed plan: skip the Phase 2 questions, but still run Phase 3 and Phase 4.
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.

