phax-decide-plan
Skill2 starsChanged 5 months agoApache-2.0View on GitHub
Default arbitration doctrine for `phax artifact decide` on a plan and for the planning agent's technical arbitrations when no human is in the session — split by shippable surface, acceptance first when the surface is shown and an acceptance provider is configured, footprint discipline, model and effort left to the planner, docs last.
In this repository16 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- boundariesSkill
- cli-view-layerSkill
- effect-servicesSkill
- find-docsSkill
- infrastructure-adaptersSkill
- model-routingSkill
- observabilitySkill
- phax-cliSkill
- phax-decide-reviewSkill
- phax-decide-specSkill
- phax-planningSkill
- phax-reviewSkill
- phax-specSkill
- state-machinesSkill
- validation-boundariesSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
If an option changes the item's public surface (adds, removes or alters a command, flag, config key, file format, API or UI the spec …
- Very specific: line 38
Every id below ranks under one of the author's five pairs, and all five stand on one ground: E0 explicit over implicit — attribution needs …
- Distinctive: line 50
Before 1.0 there is no stability contract: break freely so the surface stays *coherent*.
- Very specific: line 66
Ask who consumes: what a human reads falls under C5 (minimal, for a named reader).
- Distinctive: line 102
Follow the catalog rule of the planning skill (default Opus-tier, Sonnet for mechanical work, a stated reason for anything above, the …
≈ “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.
Files
Bundled default doctrine, landed by hand on 2026-09-24; wired into the skill catalog by the
artifact-decideplan. A project extends it with--doctrine <file>or replaces it with a project-scoped skill of the same name.
phax decide — plan doctrine
You are arbitrating a plan's technical arbitrations — the choices the spec left open
("what, not how"): contract shapes, phase decomposition, which layer owns a behaviour,
what a phase may touch. The phax-planning skill says: frame every option by its
dominant loss, recommend the option whose loss is acceptable. This doctrine says what
to do when there is no human to ask.
A plan's unsettled arbitrations are its open questions, in the same shape as a
spec's: { id, question, options: [{ id, label, abandons }], recommendation, rationale },
where recommendation is the id of one option. The plan keeps two sections, open
(preamble.openQuestions) and arbitrated (preamble.arbitratedQuestions); a decided
question moves from the first to the second with its verdict. The framing questions
F1–F5 come from decide's prompt, not from this doctrine.
The headless clarify gate (P1)
The planning skill stops and asks a human when two viable approaches sacrifice different things. Without a human, classify first, mechanically:
- If an option changes the item's public surface (adds, removes or alters a command,
flag, config key, file format, API or UI the spec claims) or contradicts a §9
decision, it is a spec question: escalate it to
decideon the spec (spec doctrine, fresh session); do not resolve it in the plan. - Otherwise resolve it by dominant loss and record it in
## Technical arbitrations.
The ground and the five principles
Every id below ranks under one of the author's five pairs, and all five stand on one
ground: E0 explicit over implicit — attribution needs explicit things; decisions are
dated, what is abandoned is written, "deliberately not" is recorded.
C1consistent over new — the existing default, discipline, source or gesture before a new one.C2strict over loose — refuse rather than warn; deviate only toward the stricter.C3exhaustive over convenient — total on inputs and states; write what is left out.C4condition over control — a condition the system verifies rather than a procedure a human drives; structural impossibility rather than a check.C5surface convenience over core convenience — the reader's and consumer's ease before the implementer's; never an arbitration "because it is simpler in the code". Before 1.0 there is no stability contract: break freely so the surface stays coherent; from 1.0 the contract is signed and the surface stays stable (semver). At every boundary the surface states the need and the core may propose what costs the surface nothing (phax-planning, Boundary contracts).
Attention is the cost of reading, not writing. Writing is free and there is no team
memory; a human reads code they did not write. Strict, exhaustive, explicit form does not
spend that attention, it frees it: every attributed guarantee is something the reader
need not verify. So the five pairs need no "limit on rigor"; the only line to draw is
C5's — exhaustive where a machine consumes, minimal where a human reads (surfaces,
handoffs, docs, the PR's tables).
Precedence when two pairs conflict.
E0is eligibility, not a tie-breaker: an option that leaves something implicit is not a candidate.- Ask who consumes: what a human reads falls under
C5(minimal, for a named reader); what a machine consumes falls underC3(exhaustive). They partition, they do not conflict. C2beatsC1only when the existing thing is loose — a principle is violated; otherwiseC1, the existing default stands. A refusal that widens the artifact is not "strict", it belongs to another artifact.- Among what remains,
C4: the option expressed as a condition the system verifies over one that needs control.
Principles (cite by id)
P1(C4) Classify, then decide. Surface or §9 → escalate; else dominant loss.P2(C5) Split by surface, not by size. Each plan ships a piece of surface that is useful on its own; split when two pieces are useful separately, never split a piece that is only useful whole. Six phases or eleven planned files in one phase are smells that make you ask the question; they are not the rule.P3(C4) Acceptance first, when the surface is shown and a provider is configured. When anacceptanceprovider is configured (phax.json or its overlays; the headless authoring prompt says whether one is) and the spec shows the surface with real before/after artifacts, write the tests in an acceptance phase that precedes the passing phase; the passing phase changes those files only by removing the markers, judged by the acceptance provider. With noacceptanceprovider, or when the surface is only described, keep test and code in one phase and rely on the compliance review'stestsdimension. If an acceptance test written first turns out wrong, the passing phase changes it only by removing the markers: the run pauses and the disagreement goes back to the spec — that is the intended behaviour, not a failure. An acceptance test is the acceptance loop, never the inner one: it tests the shown surface through a stable entry and traces to an acceptance criterion, its generators and tables are acceptance test files too, and the unit tests that drive the code's design stay in-phase (see the planning skill's "What makes a good acceptance test").P4(C2) A fix stays inside the run's footprint. A correction phase may touch the files the findings name plus the run's declared footprint. A root cause outside it is not fixed here: it becomes adeviationto escalate (a spec amendment or a new plan).P5(C3) Optional files: three per phase, named. Regenerated artifacts (lockfiles, generated references, renders) are declared once at plan level as regenerated files, outside the quota. A phase that needs more splits or declares.P6(C4) Model and effort are the planner's. No doctrine fixes effort by phase kind. Follow the catalog rule of the planning skill (default Opus-tier, Sonnet for mechanical work, a stated reason for anything above, the lowest effort that succeeds); the usage guard protects the operator's margin.P7(C5) Docs last. The item's explanatory docs page is the last phase, fed by the generated reference and the previous phases' handoffs; it also closes the item's explanatory hole.P8(C1) Inside-out to implement, outside-in to plan and verify (from the planning skill; kept here so a decision can cite it).P9(C1) Amend, don't drift. When execution shows the spec was wrong, the plan does not quietly deviate; the spec gets a dated amendment and the plan is adjusted against it.
Not choosing: propose and escalate, in three modes
Choosing is not the only move. When no option fits — the question is badly posed, a finding is wrong, an option outside the menu is better — the arbiter proposes and escalates: it writes its proposal (another option, a better question, a dismissed finding with its reason) and asks for a human arbitration. Its proposal never wins by itself. At equal value, prefer the option cheaper to reverse (reversal is a cost that grows toward production; only the destructive is a floor). Three modes:
- interactive — the human decides everything, the agent facilitates. The doctrine is written for this mode first: arbitration is where human attention belongs.
- headless — the agent decides within the menu and escalates what is off-menu, what changes the public surface, what reverses an earlier decision.
- verdicts —
phax artifact decide --verdicts: not the agent-decidesheadlessmode above. A person has already chosen, and the writer transcribes their choices. For each verdict it writes the advocate, the principles, the reversibility, thephasethe question belongs to and, for a departure, the plan revisions the choice implies andrevised. A verdict that chooses the recommendation after a departing verdict restores it: the writer undoes that departure's plan revisions and names the sections it restores inrevised([]when the departure revised nothing; either when the departure records no revised sections, as a hand-authored Decision block does). Any other verdict that follows hasrevised: []. phax setswhy(the person's note, or the question's rationale when there is none),byandat. The writer never adds an option and never changes a choice. - headless total — later, not implemented: no escalation; the agent decides; its reservations and proposals are recorded as information for the reader; the one floor is that a destructive decision stops instead of being taken. What the headless mode escalates in practice will say whether this mode is wanted and with which floor.
In every mode the proposal is recorded (escalate or note), so a mode without
escalation defers the best move instead of losing it. Escalations are counted by the
caller; an arbiter that escalates everything is visible.
Output
The spec doctrine's verdict, with principles citing P* ids (and E0, C1–C5), and
a required phase. A decided question keeps its id, question, options,
recommendation and rationale, moves to preamble.arbitratedQuestions, and carries:
{ "kind": "decided", "chosen": "split", "abandoned": ["merge"],
"why": "…", "advocate": "The strongest case for merge: …",
"principles": ["P2"],
"reversibility": "cheap" | "costly" | "irreversible",
"revised": [], "phase": "phase-02" }- The choice:
chosenis an optionid, or the reservedother, implicit on every question and never listed among the options;abandonedis exactly the other listed option ids, so every listed option whenchosenisother. - The citations:
principleslists ids that open list items in the loaded doctrine (this skill and any--doctrinefile). - The body:
revisednames the plan sections the verdict changed, empty when none; a verdict that departs from the recommendation names at least one. - The phase:
phaseis thephase-NNid of a phase the plan has, the one the decision concerns most. - The attribution: phax sets
by(the operator, by the committing git identity) andat, and keeps the plan'ssourceSpecandcompletesSpecas they were. - The record: a re-arbitrated question keeps its previous verdict at the end of
history.
The plan is not approved while an open question remains. The headless modes above record
a proposal as escalate (a spec question goes to decide on the spec); the interactive
verdict has no such field — the operator decides.
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.

