agentleFS
imMamdouhaboammarimMamdouhaboammar/anti-slop-engineering/skills/decision-guard/SKILL.md

decision-guard

Skill4 starsChanged 31 days agoMITView on GitHub

Use when an AI agent is deriving metrics or complex explanations while a direct answer may exist, choosing a software architecture or technology stack, or making consequential technical decisions with long-term operational costs and uncertain assumptions. Do not use for narrow, fully specified implementation or routine bug fixes.

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not use this Skill to override a signed constraint, silently change an authorized roadmap, or block routine work with speculative …

    line 30
  2. Distinctive:

    Observed before derived: Search available authoritative sources and native capabilities for a directly observable answer before designing …

    line 35
  3. Distinctive:

    Future is a scenario, not a fact: Test migration, failure, growth, maintainability, exit cost and recovery conditions without invented …

    line 39
  4. Distinctive:

    Interrupt on material discovery: If a verified direct answer or decision-changing constraint appears, stop unnecessary work and show the …

    line 40
  5. Distinctive:

    [Decision method](references/decision-method.md): Read in full before architecture comparisons or conflicting evidence classification.

    line 80
  6. Distinctive:

    [Decision record](references/decision-record.md): Read in full before writing or validating a persistent decision.

    line 81

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

Decision Guard

Find the direct answer, challenge the premise, then defend the smallest credible decision over its useful lifetime.

Why This Skill Is Needed & Target State

Agents can execute a flawed plan with impressive local correctness: derive a value already exposed directly, accept the user's solution as the problem, or default to a familiar framework-host-database bundle without examining operational consequences. Repeated agreement and earlier investment do not establish that the premise is sound.

The target is an interruption-capable decision process grounded in checked sources, independent alternatives, explicit reversibility, and conditional recommendations. It may conclude that no new implementation is needed. It must never imply that a completed checklist proves the choice is correct.

Activation and boundaries

SituationBehavior
Complex inference, simulation, or metric derivationRun the direct-observation path before constructing a proxy
Framework, infrastructure, database, vendor, or data-boundary selectionCompare independent architectural axes and future stress conditions
Long-running project reveals evidence that undermines its original premiseReopen the decision; do not defend sunk cost
Existing, approved implementation and no new material evidenceContinue normal execution; avoid recurring decision theater
Small bug, agreed specification, or reversible local refactorDo not activate; use Anti-Slop Engineering BUILD/FIX gates

Do not use this Skill to override a signed constraint, silently change an authorized roadmap, or block routine work with speculative hypotheticals. If a consequential recommendation conflicts with user authority, report the evidence and seek a decision rather than changing course unilaterally.

Invariant Rules

  1. Goal before method. Restate the wanted result separately from the user's proposed technique.
  2. Observed before derived. Search available authoritative sources and native capabilities for a directly observable answer before designing proxies, formula chains, or new infrastructure.
  3. Evidence types stay distinct. Label observed, derived, inferred, and unavailable claims. An inaccessible source is not a negative finding.
  4. No default-stack bundles. Evaluate rendering, runtime/jobs, hosting, persistence, and operations separately when they are material. No framework mandates its most-associated host.
  5. No reverse dogma. Neither popular managed platforms nor VPS/self-hosting win by default. Compare total ownership burden and credible future states.
  6. Future is a scenario, not a fact. Test migration, failure, growth, maintainability, exit cost and recovery conditions without invented forecasts.
  7. Interrupt on material discovery. If a verified direct answer or decision-changing constraint appears, stop unnecessary work and show the evidence, even after substantial prior investment.
  8. Protect authority. A recommendation is not an authorization to deploy, migrate data, buy services, or alter protected decisions.
  9. No mechanical truth claims. decision_guard.py verifies record completeness only; independent source review and domain tests remain mandatory.

Decision router

Evidence stateRequired actionExit condition
Direct answer found and semantics verifiedRecommend direct use; identify redundant workUser accepts the revised plan or retains the old one explicitly
Potential direct source not inspectedInspect it using available read/search/query toolsEvidence found, disproved, or marked unavailable
Source unavailable or conflictingRecord unknown, competing hypotheses, next probePause consequential commitment; do not manufacture certainty
Architecture options materially differDecompose axes and compare two serious choicesTrade-offs, constraints, reversal and future stress are visible
Strong contract or regulation excludes a candidateEliminate that candidate, explain the authorityRemaining candidates satisfy hard constraints
No meaningful choice or only routine reversible workHand back to parent BUILD/FIXNo unnecessary decision packet

Execution Workflows

  • Investigate for direct answers, metrics, hidden data, assumptions and path dependence.
  • Architect for tech-stack, vendor, infrastructure and multi-year lifecycle decisions.

At the start of either workflow, inspect the repository or data inventory, the user goal and the decision authority. Use tools available in the host; do not assume browsers, credentials, or remote environments exist.

Mandatory reassessment triggers

Reopen only when new evidence changes a critical assumption, a credible simpler option appears, a target constraint changes, an option fails a critical proof, or a project's operating conditions cross the recorded revisit trigger. Do not ask for repeated reevaluation on every ordinary edit.

Output and verification

Present the decision in this order:

  1. Goal and current recommendation: one sentence each, including proceed, pause, or stop.
  2. Direct-path result: observed finding and source, or exact unknown and next probe.
  3. Options: viable alternatives and meaningful differences; separate architecture axes when relevant.
  4. Reasoning boundary: facts, assumptions, operational owner, downside, reversibility, stress/revisit trigger.
  5. Handoff: what can execute, what requires user authority, and what evidence remains unverified.

When the decision is consequential or likely to be revisited, save a JSON decision record following record contract. Audit it with npx anti-slop-engineering decision audit <record.json> --json (or python3 scripts/decision_guard.py audit <record.json> --json from the repository root). Exit 0 means structurally complete, exit 2 means incomplete; neither proves the underlying recommendation. Do not create a record for trivial tasks.

Domain References

  • Decision method: Read in full before architecture comparisons or conflicting evidence classification.
  • Decision record: Read in full before writing or validating a persistent decision.

Failure taxonomy

FailureObservable signalRecovery
Premise capturePlan accepted as the goalReframe objective, try direct observation
Source omissionDerived claim without source inventoryCheck source/tool/schema/documentation
Context momentumSunk cost cited to preserve redundant workCompare forward costs only
Default bundle biasFramework, host and DB decided as one brand bundleSplit selection axes and trace constraints
Reverse biasVPS/self-host or new framework assumed inherently superiorCompare ops owner, backups, support and reversibility
Forecast theaterExact future pricing/load presented without evidenceReplace with scenario ranges and measurement plan
Ritualistic skepticismEndless options and objections after evidence is sufficientDecide, record invalidation triggers, resume delivery

Delegated Skills

  • anti-slop-engineering: Resume BUILD/FIX/REVIEW and the Seven Gates after the choice is established.
  • future-scale-gate: Formally model long-term operating envelopes and reversal costs for irreversible structural commitments.
  • root-fix-gate: Trace architectural invariant ownership when deciding whether to refactor or preserve a boundary.

Completion and limits

Finish when the direct route has been checked or honestly marked unknown, consequential alternatives and constraints have been compared, the user can understand what would invalidate the recommendation, and the next permitted action is explicit. A decision can validly end in pause or stop. Behavioral evaluation scenarios live in evals/scenarios.json; they are test cases, not claims of live-model results.

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.