agentleFS
lbdremylbdremy/phax/.claude/skills/phax-spec/SKILL.md

phax-spec

Skill2 starsChanged 5 months agoApache-2.0View on GitHub

Write or review a spec under docs/specs/ that the phax-planning skill will turn into a plan.md — functional behavior and consumption surface, EARS requirements, testable acceptance criteria, lifecycle and traceability.

The file

Show its rules and text

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use this skill when you are asked to write or review a spec — the artifact under docs/specs/ that captures _what_ a change must do and …

    line 8
  2. Very specific:

    Every spec carries a status key in its YAML frontmatter block, drawn from a fixed set.

    line 32
  3. Very specific:

    Never compute the stamp yourself.

    line 82
  4. Very specific:

    Keep a spec to 1–3 pages. If it grows past that, the feature is too big — split it into separate specs.

    line 88
  5. Very specific:

    Start every spec with this frontmatter block, then the ten numbered sections.

    line 93
  6. Distinctive:

    Every requirement in §5 must follow one of the five EARS (Easy Approach to Requirements Syntax) patterns.

    line 232
  7. Distinctive:

    Show, don't describe: Every element appears as the artifact the consumer will see — a config block with real field names, a real payload, a …

    line 276
  8. Distinctive:

    No surface, no section?: If the change genuinely has no consumer-visible surface (a pure behavioral fix behind an existing interface), say …

    line 292
  9. Very specific:

    Every surface element carries a summary: one sentence, in the consumer's words, saying what the consumer can now do or sees differently.

    line 298
  10. Very specific:

    Write each criterion in Given / When / Then form, against observable behavior.

    line 324
  11. Very specific:

    Every criterion traces back to a §5 requirement with a (refs §5.N) citation.

    line 327
  12. Distinctive:

    When a spec must choose between viable options, do not weigh symmetric pros/cons lists: both columns fill endlessly, everything appears to …

    line 339
  13. Distinctive:

    Every behavior is gate- or test-verifiable: If an acceptance criterion cannot be checked by a test or a gate, the requirement is too vague …

    line 369
  14. Distinctive:

    Explicit over permissive: Prefer per-variant enums and named cases over a permissive superset that admits nonsense combinations.

    line 374
  15. Distinctive:

    If a requirement reads like an implementation, it is in the wrong layer.

    line 385
  16. Distinctive:

    When asked to review rather than write, check, in order:

    line 475

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

phax spec skill

Use this skill when you are asked to write or review a spec — the artifact under docs/specs/ that captures what a change must do and why, before any planning or code.

A phax spec is the input spec: it exists to be consumed once — by the phax planning skill to produce a plan.md, and by the executing agents to write tests — then it is archived. The durable source of truth after that is the code and its tests, never a spec file kept in sync by hand.

Where the spec sits in the phax pipeline

spec (this skill)  →  plan.md (phax-planning)  →  phax plans lint  →  phax run (extraction + gates + reconciliation)
   what & why            how, decomposed            mechanical check        executable enforcement

A spec is functional behavior and consumption surface: the what and the why, never the how. Technology choices, file layout, module names, and phase decomposition belong to the plan, not the spec. The one part of the visible shape that DOES belong here is the surface — what the consumer sees and touches (commands, config keys, endpoints, screens); see the Surface section below. If you find yourself naming functions or sketching internals, you have left the spec layer.

Lifecycle

Every spec carries a status key in its YAML frontmatter block, drawn from a fixed set. phax enforces it: the value must be one of these exact strings, and a terminal status (Abandoned, Completed) must live under docs/specs/archive/ — status and location must agree, or validation fails.

Draft ──▶ Approved ──▶ Completed
  │           │
  └──▶ Abandoned ◀──┘
  • Draft — under authoring; ambiguities still open; not yet eligible for planning.
  • Approved — the human approval gate has passed: scope is bounded, requirements are unambiguous, acceptance criteria are testable. Only an Approved spec should be planned.
  • Abandoned — dropped before it shipped (terminal). The file moves to docs/specs/archive/.
  • Completed — consumed. The spec has produced a plan and tests; it moves to docs/specs/archive/. From here on, code + tests are the source of truth. A readable spec view can be regenerated from the tests on demand — it is a derived report, not a file to maintain.

Move status through its legal transitions with the phax artifact command group (phax artifact approve|abandon|complete <path>) rather than hand-editing — it validates the transition and, on a terminal one, moves the file into archive/ for you. Record the status in the frontmatter block (below) and keep it accurate.

phax artifact approve also stamps an approved: { date, baseline } block into the frontmatter and writes the spec's own record file, docs/specs/approvals/<spec file name>.json. Both are written by phax, never by hand — treat them as machine state, not authored content. Re-approving an already-Approved spec is legal and is the supported way to record an in-place revision: it re-stamps the block and rewrites the record against the spec's current content. Approve takes --by operator or --by machine:<grant> (required without a terminal), and the record names the approver. phax artifact reopen returns an Approved spec to Draft; its bound plans are named and left as they are. Because a plan can only be approved against a recorded, unmodified spec, a plan whose Source-Spec is Approved but unrecorded (no record file under docs/specs/approvals/) or edited since its approval fails plan approval with exit 12 — re-approve the spec first. phax artifact status <spec> reports the approval date, baseline, and whether the spec has been edited since.

Approval needs an empty ## 9. Open questions section. phax artifact approve refuses (exit 12) while a question is open, headless or hand-authored, and names phax artifact decide; a hand-authored §9 that does not follow the §9 format (below) is refused too. phax artifact decide <spec> answers the open questions with the operator and moves them to ## 9b.

File and naming convention

  • One feature = one spec file: docs/specs/<YYMMDDHHMM>-<slug>.md — a ten-digit stamp (the creation minute in UTC, two zero-padded digits per field) and a slug ([a-z0-9]+(-[a-z0-9]+)*). The plan it produces mirrors the slug, never the stamp: docs/plans/<YYMMDDHHMM>-<slug>-plan.md, stamped at its own creation.
  • Never compute the stamp yourself. Create the file with phax artifact new spec <slug> — it names the file from the clock and writes the frontmatter block below; you fill in the body. Every artifact command refuses a file whose name is off-grammar.
  • Refer to a spec by its slug in prose, commits and pull requests ("the plan-prune spec"), never by its stamp. The stamp only orders the directory.
  • Keep a spec to 1–3 pages. If it grows past that, the feature is too big — split it into separate specs. A bounded spec is what makes the Draft → Approved gate meaningful.

Canonical spec structure

Start every spec with this frontmatter block, then the ten numbered sections. This is the shape phax specs converge on; follow it so specs stop drifting. The four authored keys are exact — an unknown or missing one fails validation. approved is the one optional key: it is written by phax on approval (see Lifecycle), never authored by hand — omit it until the spec is first approved.

---
status: Draft | Approved | Abandoned | Completed
date: YYYY-MM-DD
audience: implementation planning with <agent>
scope: functional behavior and consumption surface
approved:                 # written by phax on approval, never by hand; absent until approved
  date: YYYY-MM-DD
  baseline: <short-sha>
---

# <Title>

## 1. Context

<The situation today. What exists, what the reader needs to know to understand the change.
Quote the relevant config/artifact/behavior. No problem statement yet — just the ground.>

## 2. Problem

<What is wrong or missing. Why the current state is unacceptable. Concrete, specific, and
honest — the problem motivates every requirement below.>

## 3. Product goal

<The change, stated as outcome (what & why), not solution (how). Close with a guiding rule
as a blockquote — the single principle a reader can hold the whole spec against.>

> <One-sentence guiding rule.>

## 4. Terminology

<Define every domain term the spec uses unambiguously. A reader and an agent must read each
term the same way. Omit only if the spec introduces no terms worth pinning.>

## 5. Functional requirements

<The behavioral contract, as numbered subsections (§5.1, §5.2, …). Each requirement is an
EARS statement (see EARS below). Behavior only — no technology, no file names, no code.>

### 5.1 <Requirement title>

<EARS requirement, e.g.> WHEN the user submits an invalid config THE system SHALL reject it
with an actionable message naming the offending field.

## 6. Surface

<The consumption interface of the change, MATERIALIZED — show the artifact, never describe
it in prose. Config: a before → after block with the real fields. API: the actual example
request and response payloads. CLI: the invocation line and an output sketch. Visual UI:
screens/states in text plus a committed design annex. Never internals (modules, functions,
file layout). Mark each block or field **normative** (the name/shape IS the contract; tests
verify it verbatim) or **indicative** (intent binds, the planner may adjust the final
spelling) — an indicative sketch with real fields beats an accurate abstraction. Omit only
if the change has no consumer-visible surface, and say so in one line.>

### <kind>: <name> — normative | indicative

Summary: <one sentence: what the consumer can now do or sees differently>

    <the element's block: the invocation, config or payload, as the consumer sees it>

## 7. Non-goals

<What is explicitly NOT in scope. Bounds the agent's exploration and the plan's surface.
A spec without Non-goals is unbounded — always write this section.>

## 8. Acceptance criteria

<Testable Given/When/Then criteria, one per meaningful behavior, each tracing back to a §5
requirement. Name normative §6 surface elements verbatim in the criteria. These are the seed
of the E2E tests the plan will produce (see Traceability).>

### <Criterion name>

Given <precondition>, when <action>, then <observable outcome>. (refs §5.1)

## 9. Open questions

<Ambiguities you could not resolve, with a recommended default for each. This is the Clarify
gate: surface every unknown here rather than letting the planner guess. When a question is an
arbitration between options, frame each option by its dominant loss (see Arbitration below) —
never a symmetric pros/cons list. Write each question in the §9 format (below), or `None.`
when there are none. Resolve or default each before marking the spec Approved.>

## 9b. Arbitrated questions

<Questions that have been decided, each with its Decision block, or `None.`.>

### The §9 format

A hand-authored spec writes its questions so phax can read them: `phax artifact status` counts
them, and prints the first line that departs from the format when it cannot. Both sections
are h2 headings, and a section ends at the next numbered h2 (`## 10. …`): any other h2 or
heading inside it departs. `None.` alone is an empty section.

```markdown
### <id> — <question>

- <option id> — <label> — abandons: <loss>
- <option id> — <label> — abandons: <loss>

Recommendation: <option id> — <rationale>

Ids are runs of characters without whitespace; use short kebab-case ones (q-keep, keep-10). Give every option an id: phax artifact decide records a verdict by option id, and a hand-authored §9 without them departs from the format. The Recommendation: and Decision: lines name one of the question's own option ids. An arbitrated question under ## 9b. Arbitrated questions has the same block, then its decision:

Decision: <option id> — by operator (<name>), <YYYY-MM-DD>
Why: <why>

A decision that was lifted from an older spec reads Decision: <option id> — lifted, unattributed, <date>. Earlier decisions follow as Earlier decision: … lines, and the decision log is ## 12. Decision log, which phax does not read back. A Decision: block in ## 9. Open questions, an arbitrated question without one, or a bold **Q2 — …** heading departs from the format.

10. Implementation-planning note

<The handoff to phax-planning: what is settled, what is deliberately left open, and any constraint the plan must respect. Keep it to the contract — do not start planning here.>


In a hand-authored spec the `Summary:` line under a §6 element heading is guidance phax does
not check; the headless sidecar's `summary` is what phax requires.

## EARS — required for every functional requirement

Every requirement in §5 must follow one of the five EARS (Easy Approach to Requirements
Syntax) patterns. EARS forces each requirement to be atomic and testable — one trigger, one
behavior — which is exactly what makes the acceptance criteria and tests fall out cleanly.

| Pattern          | Template                           | Example                                                               |
| ---------------- | ---------------------------------- | --------------------------------------------------------------------- |
| Ubiquitous       | The system **shall** …             | The system **shall** record the applied security posture per phase.   |
| Event-driven     | **WHEN** … **THE system SHALL** …  | **WHEN** a gate fails THE system SHALL open a same-session fix loop.  |
| State-driven     | **WHILE** … **THE system SHALL** … | **WHILE** a run is rate-limited THE system SHALL show the reset time. |
| Unwanted         | **IF** … **THEN** …                | **IF** a required command is unallowed THEN the preflight SHALL fail. |
| Optional feature | **WHERE** … **THE system SHALL** … | **WHERE** publish is enabled THE system SHALL open a pull request.    |

Rules:

- One requirement = one EARS sentence. If you need "and also", split it into two requirements.
- The subject is the system (phax) or a named component — never "we" or "the developer".
- State the **observable** behavior, not the mechanism. `WHEN config is invalid THE system
SHALL reject it` — not `THE system SHALL call validateConfig()`.
- Group related EARS requirements under a titled `### 5.N` subsection.

## Surface — the consumption contract

**Surface** is the consumption interface of the change: everything a consumer can see or
touch once it ships. It is NOT the _how_ — it is the most observable part of the _what_.
The "what, not how" rule bans **internals** (modules, functions, algorithms, file layout);
it does not ban the surface. Without §6, the acceptance criteria quietly reference an
interface nobody pinned ("when publish is invoked" — invoked _how_?), the planner invents
it, and the `Draft → Approved` gate approves something vaguer than what ships — even though
the surface is exactly the part a human is best placed to judge.

What belongs in §6, by kind of change — and the form it must take:

| Change ships as | Materialize as                                                            |
| --------------- | ------------------------------------------------------------------------- |
| CLI             | the invocation line(s) and an output sketch; config as a before → after block with real keys |
| API             | example request and response payloads (error payload included), real field names |
| UI              | screens/states/actions in text, plus the committed design annex           |
| File format     | an example of the emitted/consumed file, at its user-visible location     |

What never belongs: module paths, function names, internal interfaces, storage layout — an
element earns its place in §6 only if a consumer can observe it from outside.

Rules:

- **Show, don't describe.** Every element appears as the artifact the consumer will see —
  a config block with real field names, a real payload, a command line with its output
  sketch. "The config gains a key (exact name indicative)" in prose, with no block, is the
  vagueness this section exists to kill: write the sketch with real fields and mark it
  indicative instead. When the change replaces an existing surface, show **before → after**,
  quoting the current shape as it really is today.
- **Mark every element normative or indicative.** Normative: the exact name/shape is the
  contract — acceptance criteria cite it verbatim and tests verify it as written. Indicative:
  the intent binds but the planner may adjust the final name/shape. This marking is the
  guard against over-specification — freezing a flag name early is sometimes premature, but
  that must be an explicit choice, never vagueness by omission.
- **Visual UI: text carries structure, an annex carries design.** The section lists screens,
  states, and actions in text; the visual design lives in a design artifact (image, wireframe,
  Figma export) committed next to the spec and referenced from §6, with the same
  normative/indicative marking. The annex is part of the spec — archived with it, spent fuel
  like the rest.
- **No surface, no section?** If the change genuinely has no consumer-visible surface (a pure
  behavioral fix behind an existing interface), say so in one line rather than omitting the
  section silently.

### The summary of each element

Every surface element carries a `summary`: one sentence, in the consumer's words, saying what
the consumer can now do or sees differently. It never says where the change lives and never
how it is built. It is one line. The consumer depends on the kind: for `cli:` and `config:`
it is the operator, for `file:` and `api:` a reading tool or person, for `package:` a
dependent package, for `internal:` the phax code or agent that relies on it.

Good: Running `phax validate` checks each assignment bound against the routing catalog.
Bad: Adds a bounds check to the validate command's config loader.

**Users read `summary`, `before` and `after` in the release notes**, which print the summary,
then `after` and `before` as examples. So `summary` is one user-facing sentence starting with
a capital letter, and `before` / `after` are short real examples (about 20 lines at most): the
command and its output, or a file excerpt. Keep implementer notes out of them: no
indicative/normative remarks (that is `binding`'s job), no § references, no criterion or
question ids. A `$schema` URL names the release that ships the change.

An element lifted by `phax artifact migrate-documents` carries the placeholder
`(summary to write — lifted by phax artifact migrate-documents)`. The author replaces it with
the same sentence in the sidecar and on the §6 `Summary:` line, and `phax artifact approve`
and `complete` refuse the spec until they do.

## Acceptance criteria and traceability

Acceptance criteria are the contract made executable. Treat them as the **specification of the
E2E tests** the plan will write.

- Write each criterion in **Given / When / Then** form, against observable behavior. Where a
  §6 surface element is normative, cite it verbatim (``when `phax publish` runs…``), not by
  paraphrase ("when publish is invoked").
- Every criterion **traces back** to a §5 requirement with a `(refs §5.N)` citation. Every §5
  requirement should be covered by at least one criterion — an uncovered requirement is either
  untestable (rewrite it) or unowned (add a criterion).
- The plan that consumes this spec **cites these criteria and §5 requirements** in its phases
  (`refs spec §5.2, AC "…"`), and the agents turn the criteria into E2E tests. This is the
  chain that lets the spec be archived safely: the behavior now lives in tests, and a spec
  _view_ can be decompiled from those tests later. The original intent/rationale that does not
  fit a test (perf budget, security posture, UX feel) lives in the spec's Context/Product goal
  and, after archival, in commits/PRs — not in a maintained spec file.

## Arbitration — decide on the dominant loss

When a spec must choose between viable options, do not weigh symmetric pros/cons lists:
both columns fill endlessly, everything appears to weigh the same, and the list ends up
justifying whichever preference came first. Instead, name — per option — the **dominant
loss**: the strongest thing you abandon by choosing it. The decision becomes a comparison
of losses, and the recommendation states which loss is acceptable and why.

Format, inside a §9 question (the §9 format above):

```markdown
### <id> — <the arbitration>

- <option-a> — <label> — abandons: <the strongest thing this choice gives up>
- <option-b> — <label> — abandons: <the strongest thing this choice gives up>

Recommendation: <option-a> — <why its loss is the acceptable one>.

One line per option is enough. If you cannot name what an option abandons, you have not understood the option yet — that, not a longer pros list, is the signal to dig further.

Doctrine

  • What, not how. Functional requirements describe behavior. The moment a requirement names a function, a module, a library, or a phase order, it has crossed into the plan's territory — move it to the Implementation-planning note as a constraint, or drop it.
  • The surface is what, not how. Commands, config keys, endpoints, screens are the contract the consumer touches — pin them in §6 (normative or indicative), never leave them for the planner to invent. "No internals" and "no surface" are different rules; only the first holds.
  • One feature, one spec, 1–3 pages. Bounded scope is what makes approval meaningful and keeps the agent's exploration tight.
  • Every behavior is gate- or test-verifiable. If an acceptance criterion cannot be checked by a test or a gate, the requirement is too vague — sharpen it until it can.
  • No back-compat shims in persisted behavior. Consistent with phax's schema policy: new fields/behaviors are required, removed ones are removed (rejected at validation), not retained as ignored-optional. Say so in the spec when it applies.
  • Explicit over permissive. Prefer per-variant enums and named cases over a permissive superset that admits nonsense combinations. Specify the exact allowed set.
  • Arbitrate on what you abandon. A trade-off is decided by comparing dominant losses, not by counting advantages. Name, per option, the strongest thing given up; recommend the option whose loss you accept.
  • The spec is spent fuel. It is consumed once to produce the plan and the tests, then archived. Do not design it to be maintained alongside the code.

Anti-patterns to avoid

  • Over-specification. "When a spec becomes pseudo-code, you've written the program twice." If a requirement reads like an implementation, it is in the wrong layer.
  • Implementation detail in §5. File names, function signatures, module paths, phase ordering — all belong to the plan, not the spec.
  • Untestable acceptance criteria. "The system should be fast/robust/intuitive" — restate as an observable, checkable outcome or cut it.
  • Missing Non-goals. An unbounded spec invites scope creep in the plan and the run.
  • Unstated surface. Acceptance criteria that say "when publish is invoked" against a §6 that never pinned the command: the planner ends up inventing the interface the human never approved. Pin it in §6 — or mark it indicative, explicitly.
  • Internals dressed as surface. Module paths, function signatures, or internal interfaces listed in §6. If a consumer cannot observe it from outside, it is not surface — cut it.
  • Prose surface. A §6 made of descriptions ("a registration exists, form indicative") with no materialized block. Described-only surface is still unstated surface — the planner ends up inventing the artifact anyway.
  • Unresolved ambiguity smuggled into §5. Ambiguities go in §9 (Open questions) with a recommended default — never hidden as a vague requirement.
  • Symmetric pros/cons. An advantages/disadvantages list where everything weighs the same and the recommendation appears from nowhere. Restate each option as its dominant loss and arbitrate on that.
  • False confidence. Matching a wrong spec satisfies no real requirement. The value is the thinking done while writing the spec, not the document itself — interrogate the problem.
  • Free-floating requirements. A §5 requirement with no acceptance criterion, or a criterion with no refs §, breaks the traceability chain that lets the spec be archived.

Headless authoring

Everything above describes the Markdown spec you write in an interactive session. When the session is spawned by phax artifact new spec <slug> --headless --brief <file|->, the deliverable changes: you return the spec document — a JSON object — and phax renders it deterministically to the canonical structure above, writes the .md with its JSON sidecar beside it, and commits both. The doctrine does not change; only the container does.

  • The JSON object is your final message, alone: no code fence, no commentary before or after it. The prompt carries the authoritative JSON Schema; phax artifact schema spec prints the same schema.
  • Write no files. phax writes, renders and commits; a file you write is not the artifact.
  • Every key is required. An empty section is an empty array or an explicit variant (before: null, docsPage.kind: "none"), never a missing key. Unknown keys are rejected.
  • Plain text, not Markdown structure. Headings, numbering, refs § citations and the None. placeholders are rendered by phax.

Top-level keys, with the section each renders to:

KeyShapeRenders to
version, kind1, "spec"—
titlestring# <Title>
ground[{ path, note }] — files you read to write §1§1, a "Ground read:" list
contextstring§1 Context
problemstring§2 Problem
productGoal{ statement, guidingRule }§3, the rule as a blockquote
terminology[{ term, definition }]§4 Terminology
requirementsnon-empty [{ id, title, pattern, statement }]§5, one ### 5.N per requirement
surface[{ surface, summary, binding, before, after }]§6 Surface
nonGoals[string]§7 Non-goals
acceptanceCriterianon-empty [{ id, name, given, when, then, refs }]§8, "Given …, when …, then …" + refs
openQuestions[{ id, question, options, recommendation, rationale }]§9 Open questions
arbitratedQuestions[] — required, and must be empty§9b Arbitrated questions
planningNote{ settled, open, constraints } — three string arrays§10 Implementation-planning note
docsPage{ kind: "page", page, reader, example } or { kind: "none", why }§11 Docs page

The constrained shapes:

  • pattern — the requirement's EARS pattern: "ubiquitous", "event", "state", "unwanted" or "optional" (see EARS above). statement is the full EARS sentence.
  • surface — the element's kind and name, prefixed by one of cli: , config: , file: , api: , package: , internal: (e.g. "cli: phax artifact schema").
  • summary — one sentence, in the consumer's words: what whoever consumes this element can now do or sees differently. Never where the change lives, never how it is built. One line, no line break; phax refuses a missing, empty or multi-line summary. See the Surface section.
  • binding — "normative" or "indicative" (see Surface above).
  • before / after — the materialized element: after is the invocation, block or payload the consumer sees; before is its current form, or null for a new element.
  • Open questions — each has two or more options of { id, label, abandons } (abandons is the option's dominant loss — see Arbitration), and recommendation is the id of one of them, argued in rationale. other is a reserved id, implicit on every question: never list it among the options and never recommend it. A decision may choose it.
  • arbitratedQuestions — required and always []: an authoring session leaves every question open, and a non-empty array is refused as an invalid document. Each question renders under its id, with option ids on its bullets and its recommendation.

Traceability is checked when phax decodes the document, and the first violation rejects it: requirement, question and per-question option ids are unique; every acceptance criterion's refs names existing requirement ids; every requirement is referenced by at least one criterion; every recommendation names one of its question's options. Requirement ids are yours to choose — phax numbers the §5 headings by position and rewrites refs to match.

Reviewing a spec

When asked to review rather than write, check, in order:

  1. Layer — is anything in §5 actually how (implementation)? Move or cut it.
  2. EARS — does every §5 requirement follow a pattern, atomically?
  3. Surface — is §6 present (or explicitly declared empty)? Is every element MATERIALIZED (before → after config block, example payload, invocation + output sketch) rather than described in prose, consumer-observable, and marked normative/indicative? Does a visual UI reference a committed design annex? Do the acceptance criteria cite normative elements verbatim?
  4. Coverage — does every §5 requirement have an acceptance criterion, and does every criterion refs §?
  5. Bounds — are Non-goals present and honest? Is the spec ≤ 3 pages?
  6. Clarity gate — are all §9 open questions resolved or defaulted before Approved? Does every arbitration name the dominant loss per option, rather than listing pros/cons?
  7. Testability — could an agent turn every acceptance criterion into a passing test without inventing intent the spec did not state?

Example well-formed slice

---
status: Approved
date: 2026-06-12
audience: implementation planning with Claude Code
scope: functional behavior and consumption surface
---

# Push Branch and Create Pull Request

## 3. Product goal

phax must be able to publish a finished run: push the run's branch and open a pull request
whose body is the run review handoff, so review happens on GitHub, not in the terminal.

> phax never publishes a run that has not passed its gates.

## 5. Functional requirements

### 5.1 Publish gating

WHEN a run has completed with all gates green THE system SHALL make the run eligible to publish.

### 5.2 Pull request creation

WHERE publishing is enabled THE system SHALL push the run branch and open a pull request whose
body is the run review handoff.

### 5.3 Idempotency

IF a pull request already exists for the run branch THEN the system SHALL update it rather than
open a duplicate.

## 6. Surface

New command (normative):

    phax publish <run-id>

Refusal, on a red gate (exit code and named gate normative; wording indicative):

    ✗ publish refused: gate "test" is red
    $? = 1

`phax.json`, before → after (key spelling indicative; presence of an enable switch normative
per §5.2 WHERE clause):

    "publish": { "auto": false }          →    "publish": { "auto": true }

Pull request: body is the run review handoff (normative); title format indicative.

## 8. Acceptance criteria

### Gates gate publishing

Given a run with a red gate, when `phax publish <run-id>` runs, then it exits non-zero and
names the failing gate. (refs §5.1)

### PR carries the handoff

Given a completed green run with publishing enabled, when `phax publish <run-id>` runs, then
a pull request exists whose body is the run review handoff. (refs §5.2)

### Re-publish is idempotent

Given a run already published, when `phax publish <run-id>` runs again, then the existing
pull request is updated and no duplicate is created. (refs §5.3)

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.