agentleFS
qengine13qengine13/forge-skills/skills/plan-hygiene/SKILL.md

plan-hygiene

Skill1 starsChanged 8 days agoApache-2.0View on GitHub

Run a pre-flight before substantive plans, scope or doctrine changes, new or revised skills and hooks, architecture-bearing work, or tasks likely to exceed about 30 minutes. Verify the goal, existing substrate, statistical viability where relevant, project doctrine, prior decisions, scope boundaries, and measurable completion gates before implementation. Usually skip routine questions, tiny edits, and narrow bug fixes.

The file

Show its rules and text

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈15

    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. Distinctive:

    Read model and tool selection before selecting models or delegating.

    line 16
  2. Distinctive:

    Use evidence from current files, command results, tests, databases, authoritative external sources, or explicit user facts.

    line 29
  3. Very specific:

    Do not proceed past any verdict except PROCEED without explicit user direction resolving the reason.

    line 39
  4. Distinctive:

    Ask only when a missing answer would materially change the result and cannot be recovered from current sources.

    line 58
  5. Distinctive:

    Do not turn a missing dependency into a prescribed architecture.

    line 60
  6. Distinctive:

    Verify every material assumption about existing code, files, data, routes, commands, schemas, hooks, infrastructure, or external state.

    line 66
  7. Distinctive:

    Search broadly, then read the relevant source.

    line 68
  8. Very specific:

    Use PRECURSOR_FIRST, RE_SCOPE, or KILL when an absent substrate changes cost, risk, or feasibility materially.

    line 75
  9. Distinctive:

    Run when the plan depends on experiments, cohorts, backtests, inference, replay validity, measurable effects, or performance claims.

    line 79
  10. Very specific:

    Use RE_SCOPE or KILL when the promised conclusion is not measurable within the available data or timeline.

    line 83
  11. Distinctive:

    Read the governing files directly.

    line 87
  12. Very specific:

    Use AMEND_FIRST when the plan conflicts with canonical doctrine and no separately attributable user decision changes it.

    line 94
  13. Distinctive:

    Run the environment's approved memory quick pass plus targeted repository-history search when prior context is likely relevant.

    line 98
  14. Distinctive:

    Do not write persistent memory unless the user explicitly authorizes it.

    line 102
  15. Distinctive:

    Use independent review when the user or project requires it.

    line 108
  16. Distinctive:

    Use a bounded subagent critique only when delegation is authorized.

    line 109
  17. Very specific:

    Every PROCEED artifact must include non-empty completion gates covering:

    line 118
  18. Distinctive:

    If meaningful completion gates cannot be written, the plan is not ready.

    line 126
  19. Distinctive:

    every pass has evidence;

    line 132
  20. Distinctive:

    every skip has a reason;

    line 133

≈ “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
<!-- Public edition: adapted for portable installation and subscription-aware model selection. See collection NOTICE. -->

Plan Hygiene

Make important work testable before it starts. Surface missing foundations, doctrine conflicts, unmeasurable promises, and unauthorized scope while correction is still cheap.

The user's current instruction and repository doctrine control this workflow. Do not turn a plan-only request into implementation, mutate protected files, or invent approval.

Runtime compatibility

Read model and tool selection before selecting models or delegating. The host and user control tools, permissions, subscriptions, and costs.

Inputs

Collect:

  • the user's exact objective and boundaries;
  • current project doctrine and source-of-truth files;
  • the proposed plan or the facts needed to draft it;
  • relevant code, data, commands, external state, and prior decisions;
  • the intended completion claim.

Use evidence from current files, command results, tests, databases, authoritative external sources, or explicit user facts. Memory is a recall layer, not proof.

Verdicts

  • PROCEED — the plan is sufficiently grounded and completion is testable;
  • RE_SCOPE — the goal is viable only after narrowing or sequencing;
  • PRECURSOR_FIRST — a missing foundation must be built or verified first;
  • AMEND_FIRST — canonical doctrine or an accepted decision must change first;
  • KILL — the proposed work cannot produce its promised outcome under current conditions.

Do not proceed past any verdict except PROCEED without explicit user direction resolving the reason.

Seven-gate pre-flight

Gate 0 — Trigger

State FIRES or DOES_NOT_FIRE, the reason, and a rough effort estimate. If the skill does not fire, stop the protocol and continue with the task.

Gate 1 — Goal and contract

Write:

  • one action-oriented goal;
  • audience or executor;
  • hard must-do and must-not-do constraints;
  • observable success criteria;
  • at least two plausible failure modes;
  • estimated agent effort and calendar span.

Ask only when a missing answer would materially change the result and cannot be recovered from current sources.

Do not turn a missing dependency into a prescribed architecture. Separate required behaviours from optional implementation choices; do not require a queue, tenancy model, or storage product without evidence that the actual task needs it.

Gate 2 — Substrate

Verify every material assumption about existing code, files, data, routes, commands, schemas, hooks, infrastructure, or external state.

Search broadly, then read the relevant source. Trace entry points, callers, configuration, tests, and ownership boundaries where the plan depends on them. For dependency failures, inspect installation integrity before proposing version changes.

Record:

AssumptionExists?EvidenceImpact if absent

Use PRECURSOR_FIRST, RE_SCOPE, or KILL when an absent substrate changes cost, risk, or feasibility materially. Mark this gate not applicable only for genuine doctrine-only or strategy-only work.

Gate 3 — Measurement and statistical viability

Run when the plan depends on experiments, cohorts, backtests, inference, replay validity, measurable effects, or performance claims.

State the sample or dataset, effect or threshold, instrumentation, comparison method, and whether the available evidence can support the intended claim. Include alpha, correction, power, or minimum detectable effect when those concepts apply.

Use RE_SCOPE or KILL when the promised conclusion is not measurable within the available data or timeline. Mark deterministic implementation and non-evaluative documentation work not applicable.

Gate 4 — Doctrine, identity, and architecture

Read the governing files directly. Check business identity, current project state, architecture decisions, security and compliance rules, release policy, skill routing, and edit boundaries that apply.

Record:

RequirementPlan treatmentEvidence or gap

Use AMEND_FIRST when the plan conflicts with canonical doctrine and no separately attributable user decision changes it. Invoke any mandatory specialist workflow named by the repository before proceeding.

Gate 5 — Prior decisions and failed attempts

Run the environment's approved memory quick pass plus targeted repository-history search when prior context is likely relevant. Reopen current files before relying on any recalled claim.

Record only context that changes the plan, the source used, and any unavailable evidence. A prior kill verdict remains controlling unless current evidence shows that its blocking condition changed.

Do not write persistent memory unless the user explicitly authorizes it.

Gate 6 — Challenge

For work likely to exceed two hours or alter doctrine or architecture, challenge the plan against Gates 1–5 and its predicted failure modes.

  • Use independent review when the user or project requires it.
  • Use a bounded subagent critique only when delegation is authorized.
  • Otherwise perform and label a SELF_CHECK.

Return PASS, SCOPE_CHANGE, KILL, SELF_CHECK, or SKIP_WITH_REASON, with evidence. Review findings are inputs; accept only those supported by the current task and files.

Artifact and completion gates

For substantive work, write the repository's prescribed pre-flight artifact. If no convention exists, use docs/pre-flight/YYYY-MM-DD-<scope>.md and references/verdict-template.md.

Every PROCEED artifact must include non-empty completion gates covering:

  • core promised behaviours;
  • hard dependencies and risk boundaries;
  • relevant external or user-visible surfaces;
  • exact verification evidence;
  • local, remote, review, merge, deployment, and runtime states when applicable.

If meaningful completion gates cannot be written, the plan is not ready.

Final check

Before proceeding, confirm:

  • every pass has evidence;
  • every skip has a reason;
  • the smallest useful scope was selected;
  • explicit edit, approval, deployment, and communication boundaries are preserved;
  • the plan does not treat memory, generated maps, local green checks, or agent prose as stronger evidence than they are;
  • required user ratification is separately attributable and recorded.

Return the verdict first, then the goal, material gate findings, completion gates, estimate, and any decision the user must make.

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.