agentleFS
lbdremylbdremy/phax/.claude/skills/phax-decide-review/SKILL.md

phax-decide-review

Skill2 starsChanged 5 months agoApache-2.0View on GitHub

Default doctrine for turning a headless code review's findings into a plan (`phax review-plan`) — the severity scale and its threshold, what a fix may touch, when not to plan at all, and how findings become phases.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    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
  1. Very specific:

    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 …

    line 31
  2. Distinctive:

    Before 1.0 there is no stability contract: break freely so the surface stays *coherent*.

    line 43
  3. Very specific:

    Ask who consumes: what a human reads falls under C5 (minimal, for a named reader).

    line 59
  4. Very specific:

    If two findings, or a finding and a requirement, cannot both be satisfied, the disagreement goes back to decide on the spec (spec doctrine …

    line 76

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

Bundled default doctrine, landed by hand on 2026-09-24; wired into the skill catalog by the artifact-decide plan. A project extends it with --doctrine <file> or replaces it with a project-scoped skill of the same name.

phax decide — review doctrine

You are turning code-review.json into review-plan.json. You may be resuming the review session (you remember why each finding was raised) or starting from the report alone. Either way: the report is the judge; the plan is its consequence. Do not re-review.

Severity, and the threshold

SeverityMeaningDefault treatment
bugincorrect behaviourplanned
deviationdeparture from the spec or the planplanned, or escalated when the deviation is the spec's fault (R3)
concerna risk, a missing test, a security pointplanned
infostyle, preferencenever planned; written to the handoff note

--min-severity moves the line; the caller owns it. Without it, everything above info is planned. Compliance findings of severity deviation join the report's findings — they share the scale.

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.

  • C1 consistent over new — the existing default, discipline, source or gesture before a new one.
  • C2 strict over loose — refuse rather than warn; deviate only toward the stricter.
  • C3 exhaustive over convenient — total on inputs and states; write what is left out.
  • C4 condition over control — a condition the system verifies rather than a procedure a human drives; structural impossibility rather than a check.
  • C5 surface 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.

  1. E0 is eligibility, not a tie-breaker: an option that leaves something implicit is not a candidate.
  2. Ask who consumes: what a human reads falls under C5 (minimal, for a named reader); what a machine consumes falls under C3 (exhaustive). They partition, they do not conflict.
  3. C2 beats C1 only when the existing thing is loose — a principle is violated; otherwise C1, the existing default stands. A refusal that widens the artifact is not "strict", it belongs to another artifact.
  4. Among what remains, C4: the option expressed as a condition the system verifies over one that needs control.

Principles (cite by id)

  • R1 (C4) Do not plan on a divergent compliance verdict. The run drifted from its plan; fixing code would chase the wrong target. Emit no plan; escalate.
  • R2 (C2) A fix stays inside the footprint (= plan doctrine P4): the files the findings name plus the run's declared footprint. A root cause outside becomes a deviation to escalate, not a phase.
  • R3 (C1) A finding that reveals a contradiction reopens the spec, it is not patched. If two findings, or a finding and a requirement, cannot both be satisfied, the disagreement goes back to decide on the spec (spec doctrine S8). Plan the rest.
  • R4 (C4) Acceptance tests are not fix targets. A fix phase never plans an acceptance test, nor any test, matrix or fixture that judges the code it changes. If the finding says the test is wrong, that is a question about what judges the code, for the spec: escalate (plan doctrine P3).
  • R5 (C1) Group by cause, not by file. One phase per root cause; findings that share a cause share a phase; a phase names its findings by id so the next --headless pass can tick them.
  • R6 (C4) Bounded passes. The caller bounds the passes (review.code.maxPasses); the doctrine does not retry. A finding still open after the last pass is reported, never silently dropped.
  • R7 (C3) info accumulates in the handoff, once. Style findings are collected in the handoff note for the human, deduplicated across passes; they never generate work.

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.
  • 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

review-plan.json in the phax-plan shape: one phase per cause, each phase listing the finding ids it addresses, its planned files (within R2), its gate profile (the run's), and no acceptance test files (R4). Plus a decisions[] block in the decide shape for every finding escalated under R1–R4, so the ledger shows what was not fixed and why.

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.