the01geek/prflow/spec

Completion checklist (do this first)

Before any of the pipeline's steps below, track these slots in the runner's task-tracking tool — the one that keeps a list of tasks with statuses, whatever its name. When none is visible, first load one the runner lists as not yet loaded or that its tool-search tool finds. Otherwise — and whenever the tool errors, its setup call's result shows no tracker, it stops working later, or you cannot tell whether a tool is one — keep the slots as an inline checklist in your reply, re-rendered on each status change with each slot pending, in progress or completed, keeping the statuses already reached. Change tracker only when the one in use stops working. A tracker problem never ends the run.

• [ ] 1. Run Step 1's arm and write its evidence artifact
• [ ] 2. Clarify the user story until the Definition of Ready is met (Step 2); a No change choice ends the run
• [ ] 3. Draft the issue and pass the no-options gate (Step 3)
• [ ] 4. Self-audit the draft against the code, revise, and re-pass the no-options gate (Step 3.5)
• [ ] 5. Run the draft checks and each draft's first audit round (Step 3.6)
• [ ] 6. Present the issue and obtain Step 4's filing election, then create it (sub-steps 1–5)
• [ ] 7. After filing succeeds, apply 3a's assignment and implement-offer answers (Step 4, sub-step 6)

Mark each slot in_progress when you start it and completed only when done — the canonical status vocabulary; a task tool whose status fields differ uses its nearest equivalents. Step 1's reports complete only slot 1.

Once the tracker exists, open your first reply with one line naming this skill and the tracker in use — the task tool or the inline checklist — and name any tracking tool that failed directly after it.

Iron Law

No run abbreviates or skips a step before it ends: at a created, widened or paused issue, at a stop a step documents, or at a No change — file nothing choice.

Rationalizations

Core principle

An issue is the output of resolved decisions — not a place to park unresolved ones.

The ask-or-leave test governs whether a decision is asked, written or left to the implementer. A decision the request leaves open is asked and written unless a competent implementer could clearly make it from the request and codebase and it is not a member's outcome in a fully listable set, such as an agent-policy route or a text's clause. Then the run leaves it out, naming it in one chat line; the implementer decides and PR review judges it. The implementation-approach question is asked on every run and never left to the implementer; a needed heuristic is asked as its rule, failure direction and limit.

Every decision the test does not leave to the implementer must be resolved by asking the user before drafting. A decision settled on a second delegated reply counts as resolved by the user; remaining unresolved decisions go into one explicit Blocked section.

The no-options rule. The body states one decided behavior per fork: no alternative, open question or deferred choice is written outside ## 🚫 Blocked, and a premise flagged — assumption, confirm before implementing is a fact to confirm, not an open choice. Every acceptance criterion is one concrete, unconditional assertion, and the ask-or-leave test decides what is left out. Wording the user approved this run, or the issue prescribes verbatim as text to add to a file, changes only by a decision fork asked of the user, overriding every other rule, sweep and standard; a widened issue's body is request text, not approved wording.

The pre-mortem rule — hold it for the rest of the run. From Step 2's first candidate until the run ends, assume the fix shipped as designed and failed: name the consumer, environment, input, state or later change that broke. Repeat when a candidate, answer or revision changes the design. Confirm a failure claim with a read before it shapes a recommendation, criterion or gotcha; call it unverified where no read can, and drop one the change cannot cause. Before the implementation-approach question, walk each motivating case and each named arm through every candidate. A motivating case is a reported input or run the request says the fix exists to change (when unsure, the case it describes); a named arm is a case class the candidate rule's wording distinguishes (both sides of its condition, each member of a "for every" range), walked with or without a motivating case; with neither, there is no walk. Name the outcome each should have: the requested change for a motivating case or an arm the request changes, else the arm's correct current outcome. Read the case's input, what produces it and whether it reaches the subject, and its current outcome, then derive the candidate's outcome, for text a model follows, from the clause of the candidate's text, changed or left as is, whose condition the case's input meets (its deciding clause, as references/issue-template.md's Testing Strategy defines it). A case passes only when that is the outcome it should have and, for a motivating case, the read shows its current outcome wrong; anything else, a fact no read settles included, is a walk failure, never dropped as one the change cannot cause. The draft states each failure the chosen design keeps, walk failures included, labelled unverified where no read confirms it. Surface failures before the implementation-approach question where possible, while they can still change the design.

Audit preparation. Before offering or dispatching an audit, finish the full current-draft review under references/step-3-5-self-audit.md, apply its confirmed findings, and verify the repairs and affected statements under references/revision-delta.md. Use your reads of the current draft and required sources, applied edits and completed verification to establish this; a tracker tick, disclosed gap or findings list does not establish it. For an unfinished or unestablished part, pause the audit route and name the reason, including unreadable required sources or instructions and a finding awaiting a user decision. Finish that work first; when it cannot finish before presentation, run no round, disclose the reason beside Step 4's audit summary line, and present. Review the inline body when the working-draft file never landed. A missing helper alone does not pause the route when the required review and verification can otherwise finish.

Consumer skill extension (load first)

Before doing this skill's work, load any consumer-supplied skill extension for this skill and honor it. From the repo root, run:

"${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../scripts/load-prompt-extension.sh spec

A missing helper path (No such file, exit 127, or the platform equivalent — e.g. The system cannot find the path specified on Windows shells, or a localized message) is the anchor-resolution failure described in ## Runner setup below — fix the anchor, do not report a missing extension. Otherwise, on a non-zero exit where the helper runs but fails, a consumer extension exists but could not be loaded: surface its stderr message, never silently proceed as if none existed. No PROMPT-EXTENSION-STATUS: line on stderr, as after a refusal, is an unestablished extension to report, never an empty one. Exit 0 with text: treat it as instructions appended to the end of this skill's own prompt for this run. When an exit-0 load's stderr carries a line naming a stray specs.md beside the extension, quote that line verbatim in this run's first message, before any Step 1 work, so the consumer who wrote that specs.md learns it is not read. Exit 0, no output: proceed unchanged.

Reference routing

The per-step procedures and the conditional fallback arms live in references/, loaded at their trigger and never before it; waiting on a subagent triggers nothing. Build a reference's path from this skill's directory per the Portable helper anchor rules in ## Runner setup below and read it with the runner's file-read tool — never a new shell invocation. A load is accepted only when the file's first line is its start boundary marker and its last line is the matching end marker, each naming that file's own path, with exactly one of each.

A reader that returns a file in pages — a partial-view notice with an offset/limit continuation — has not damaged it: page forward until no continuation is offered or a page adds nothing new, then apply the marker rule to the assembled whole document, and breadcrumb the recovery. A read you cannot complete, a gap in the page sequence, or a message you cannot classify as that notice is the truncated read case below. Subject to Audit preparation, every load failure takes its degraded behavior without ending the run: emit an in-chat breadcrumb naming the file and failure kind for an unreadable or absent file, an empty file, a missing / duplicated / foreign-path marker, or a truncated read. The five non-degradable invariants stated below hold on every degraded arm.

Each failed load's degraded behavior is in references/degradation-routing.md: load it (per the boundary-marker rule above) only when a reference load fails. A condition-triggered fallback loads from the path its call site names.

If references/degradation-routing.md itself fails to load, proceed inline for that step from the user story and Step 1 findings, subject to Audit preparation, and disclose the reduced coverage in chat. The five non-degradable invariants below still hold.

Non-degradable invariants

These five hold on every path, including every degraded arm above, and are load-independent of any reference: