/prflow:spec (the preferred name) or /prflow:create-issue (a permanent alias) — both run the same pipeline.
It creates one issue or widens an open issue that covers the work. Interactive runs require your approval of the final draft; non-interactive filing has narrower conditions. Unresolved decisions remain visible in the draft. At any implementation-approach question you can choose No change — file nothing: the run ends with nothing written to GitHub, gives its evidence and names any open issue it leaves for you. PRFlow recommends it only when checked evidence positively shows every reported failure is gone.
Run It
Claude Code background sessions move out of the shared checkout before saving investigation records or starting discovery agents. A session already in a worktree keeps it. If isolation is unavailable or fails, the investigation continues with its reports in chat. If the session cannot tell whether it needs isolating, it says why and continues in the current checkout without isolating. In an interactive session:1
Describe the work in your own words
2
Answer the questions
PRFlow reads the repository and documentation, then asks about unresolved scope, behavior, dependencies and verification, always including which implementation approach to take. It leaves other decisions to the implementer when they can clearly be made from your request and the codebase, unless each outcome in a complete set must be specified.Before the implementation-approach question, PRFlow checks each option against the risks and constraints it recorded while reading the repository, and for facts it never confirmed, and the question names the ones that bear on each option. When an option’s short text shortens a cost comparison the check reported, it still says whether that option adds or saves cost compared with current behavior, in which cases and under what condition, and what remains uncertain. Right after the check, before it asks, PRFlow reads to confirm each fact the check reports as unconfirmed that, if false, would change an option or its text as described below or overturn the reason an approach was passed over, and each failure the check claims. A read that disproves a passed-over approach’s reason corrects that reason and, before the check limit described below, brings the approach back as an option. The question shows a fact PRFlow read for as not confirmed only when that read failed, was refused, was cut short or came back in full neither confirming nor disproving it, or when no single read can settle it, and shows any other fact the check found unconfirmed as not confirmed, except that when PRFlow’s only change since the check is reads that each either clearly confirm a fact the check listed, seen in full, or settle nothing about it, and add no other claim, the question shows each fact so confirmed as confirmed by its own read. When the independent check cannot run or returns an incomplete or malformed result, PRFlow makes the check itself and the question says the independent check did not run.Unless the initial code and documentation checks show every reported failure is gone, PRFlow asks each open scope question whose answer could change how an option works before it checks the options, when that answer does not depend on which approach you pick or PRFlow cannot tell whether it does; a question already answered, answered by a non-interactive run itself or recorded as blocked does not hold up the check. Before each check it corrects or removes option text that contradicts what it already recorded, except in a later question’s option to leave a requested case uncovered, where it shows you the contradiction instead. It stops after two checks before each approach question, apart from a re-check that a new answer of yours requires, though it can run more when it cannot tell how many already ran; a repeated approach question gets its own limit. Before that limit, a finding changes how an option works only when it shows the option fails a reported case your request says the fix exists to change or contradicts one of your answers; PRFlow corrects option text a finding shows false or self-contradictory, except in a later question’s option to leave a requested case uncovered, and discloses in the question each other finding the check reports back. After the second check, other than for a new answer of yours, it changes no option’s design and adds, drops or swaps no option, except to remove a proposed part, outside a later question’s option to leave a requested case uncovered, when it has a stated reason and reads disprove every reason for it, at least one reported case the fix exists to change or case the option’s wording distinguishes exists, the option without it passes the walk described below, none of your answers or constraints is contradicted and no other mechanism is added or substituted. It still corrects the reasons a removal affects, and option text except in that later question’s option, saying in the question that the corrected text and each removal were not re-checked, and discloses the remaining reported findings and any failure it finds itself after that check, naming the case or answer each failing option bears on. It handles the findings of a re-check a new answer of yours requires after that check the same way. A finding the check leaves out of what it reports back is not disclosed before you pick.After you pick, PRFlow asks the approach question again when later evidence shows, for example, that a fact the question stated was wrong or that the chosen option adds a stop or
Blocked outcome the question never mentioned, and, through the usual clarification routes, asks a scope question again when evidence disproves the reason it stated or leaves it unclear. A correction to what the approach question stated that leaves the chosen option’s coverage and cost as stated or better, favours no other option more than the question stated and adds no mechanism is written into the draft without a re-ask; any other correction re-asks. Picking a different option when the approach question is asked again redrafts the issue; a reply that changes only a sub-choice of the chosen option revises the draft without a redraft.On an interactive run, a later question that would choose between different mechanisms within the picked approach, such as a different component, rule or route, is asked as the approach question again, so the option check runs before it too. A reply that keeps the picked approach with one of that question’s choices revises the draft without a redraft.Also before the approach question, PRFlow walks each option through each reported case your request says the fix exists to change and, for a proposed rule, each case class the rule’s own wording distinguishes, for example both sides of a condition it states. It reads each case’s facts, and for instructions a model follows it reads a case’s outcome from the instruction that decides it. It reports a case that fails the walk, for example one the option would not fix or would wrongly change, where possible while you can still pick a different design.When the evidence claims a complete set of readers for something the change removes or alters, for example a value, text, call or file write, PRFlow follows what that change outputs through the values and steps that carry it onward to the code and instructions that read it, and records each path.PRFlow drafts the issue from the facts it recorded earlier in the run that bear on the approach you picked, including risks, premise corrections, edge cases and option-check facts, for example a risk your chosen design keeps. Each lands in the draft as handled, as an accepted limit or as not established, keeping, for example, the conditions and phases the record names; a failure the chosen design keeps, such as a case that failed the walk above, is marked unverified when no read confirms it. Option-check facts come from every check the run made and can still read, not only the last. A claim from your request or from PRFlow’s recorded analysis of it that the draft repeats, and that the premise corrections or recorded evidence contradict, appears in its corrected form. The self-audit then checks the draft against those facts it can read, unless its instructions fail to load.Other questions that mark an option (Recommended) also name evidence PRFlow already read or recorded that argues against that option, against a premise the question states, or for an option it does not recommend, for example a comment on your issue, so you can weigh it before you choose. PRFlow does not read anything new to find it.A question can wait for another answer, for example your approach choice, that decides, or leaves PRFlow unable to tell whether it decides, whether the question applies or what its options say or lead to. Independent, ready questions can share a batch. For a bug report, PRFlow collects the trigger, actual and expected behavior, and environment.PRFlow also asks which meaning you intend when a word in your request means something different in the repository docs or code it has read, or could name more than one thing there, and the difference changes, or may change, what gets built. It does not ask when your request already states its meaning and names the repository meaning it replaces. A word that means the same thing in your request and your repository costs no question.Before excluding a case you requested, PRFlow reuses your agreement or asks, explaining the remaining work and known tracking status. Declining keeps the case in scope; silence pauses the interactive run.Answering “you decide” or “I don’t know” makes PRFlow research the question and re-ask it with each option’s pros and cons and, where the evidence supports one, a recommendation. A second such reply selects the recommendation and tells you why, or leaves the question in Blocked when there is no recommendation. Two choices stay conservative: file a new issue instead of widening one, and retain a requested case instead of excluding it. “You decide” or “I don’t know” on a question PRFlow recognizes as one only you can answer, such as your release plans, sends it to Blocked without research or a re-ask; when unsure, it researches.PRFlow sets no limit on how many questions it asks. A reply such as “just create it” is handled like “you decide”: it settles only the questions it answers, and PRFlow still asks each other open question. Non-interactive runs record an unresolved scope question in Blocked.If nobody can establish a fact, PRFlow records it as unestablished rather than guessing. That includes, for example, a fact resting on lines that a head -30 PRFlow ran never printed, when PRFlow neither read those lines in full nor counted the matches with nothing cut.3
Review the saved draft
PRFlow writes the draft to a file and saves the supporting investigation record beside it. The filing question’s text says how many corrections PRFlow applied after the latest audit round, or that the draft is not audited. Its option preview shows the draft’s path and title, the audit summary line, any reason the implementation offer is withheld, any answers carried from an earlier prompt, any audit findings PRFlow did not fix, any draft-check problems still standing, the record’s path (or says the record is empty), each decision settled after you left it to PRFlow a second time, one line for each choice PRFlow made itself (labelled as the run’s choice, so you see it before approving) and the self-audit summary; where no option preview is shown, PRFlow prints these in chat just before the question. A run’s choice is a decision the draft states that PRFlow made during Answer the questions, while drafting or while revising, did not leave to the implementer, and that your request does not state and none of your answers or requested changes chose; advice an agent wrote, such as a pasted challenge result, states no decision even inside your request, though the problem an agent-written body reports does; a decision you left to PRFlow a second time keeps its own line rather than being listed again. A non-interactive run prints all of this in chat, and a re-ask after no reply, or a reply PRFlow cannot act on, repeats in chat the question text and any of this not yet shown there. If PRFlow’s Step 4 instructions fail to load, it prints the full draft and the audit summary line in chat and, in an interactive run, asks for your approval. It prints the complete title and body, followed by the record, in chat when you choose print the full draft in chat at the decision question below, and unasked when it cannot show you a saved draft path or runs non-interactively.
4
Decide, then approve
PRFlow runs one audit round on each saved draft before you first see it, once preparation is finished. You choose whether to spend another audit round, then approve that exact draft or ask for changes. You also answer whether to assign the issue to yourself and, when offered, whether to start implementation: on a runner that asks several questions at once, with that decision, each answer carrying to later prompts until you approve and shown there so you can change it; on one that asks one question at a time, right after you approve. PRFlow creates nothing until you approve, acts on your answers only after creating the issue, and asks nothing afterwards.
What PRFlow Produces
The issue body follows a fixed structure:## Dependencies and ## 🚫 Blocked — resolve before implementation are added when they apply.
When the change edits instructions a model follows, such as an application’s prompt, the testing strategy says for each case the change exists to fix whether that case is replayed (run with the old and the new instructions on the same scenario). For a replayed case it says what the scenario must keep so the failure can still happen. For example, it keeps an input the model must look up, and it leaves out the answers the new instructions oblige the model to find for itself. For a case that is not replayed, it names what triggers the failure and why no replay can recreate it. When PRFlow cannot tell, it marks the case replayed. For a replayed case it also says whether the failure needs the context of the run it happened in, such as a long conversation. Each case’s expected result is what the new instructions decide for it: the issue quotes and names the instruction whose condition the case meets. When it cannot tell which instruction decides the case, it names each one that might and accepts any of their outcomes except the current one. A case that none of the new instructions decides the way the change requires is dropped as a case the change exists to fix. The implement workflow follows this statement and skips the replays it rules out.
When the issue asks the implementing run to replay or test with a recorded input PRFlow read, the testing strategy quotes the input’s fields that decide the case next to the source it cites; a long input is quoted only in part and cited for the rest.
After creation you get the new issue’s URL, and the PRFlow label is applied when repository permissions allow it.
## Technical Context and ## Implementation Notes are implementer reference material, so their contents ship inside a <details> block and render collapsed on GitHub — every other section renders open. Expand them to read the detail; agents read the raw body text either way.The Second Comment Is Expected
PRFlow splits its output into two artifacts, and you will see both.- The issue body is the implementer’s brief. It holds only what a competent implementer cannot safely work out on their own: the problem, the desired behavior, non-obvious scope decisions, the acceptance criteria, real hazards and dependencies. It is the only channel implement takes acceptance criteria from.
- The investigation record is posted as a comment on the created or widened issue. It holds the narrative PRFlow sorted out of the body while drafting: supporting evidence, audit history, lower-severity hazards, rejected alternatives and anything the repository would rediscover during implementation anyway. When the run passed over heavier approaches, PRFlow adds one
Considered-and-rejected:line counting them. When PRFlow revises the draft, it also replaces record text the revision makes false or supersedes. A record over 65,536 bytes, or one that cannot be built or saved, is not posted.
Approval Points
Before offering or starting an audit, PRFlow finishes reviewing the current draft, applies its confirmed findings, and verifies the repairs and affected statements. If any of that work is unfinished or cannot be established, it pauses the audit and tells you why. This includes required sources or instructions it cannot read and a repair awaiting your decision. When that work cannot finish before you see the draft, PRFlow runs no audit round and shows the reason beside the audit summary line. In an interactive run, enough context alone does not authorize filing:- Review the draft PRFlow saved to a file, whose path it shows. Ask for the complete title and body in chat when you want them, by choosing print the full draft in chat.
- Choose whether to spend another fresh-context audit round on the draft. Once preparation is finished, PRFlow runs one round before you first see each saved draft and fixes the must-revise findings it confirms. It can also apply an advisory finding whose fix deletes the attacked text or moves it to the investigation record, and the approval question counts each one it applies among the corrections. Whenever a prepared saved draft’s audit summary reads
final bytes NOT audited, PRFlow offers another round as the first, recommended option, however many rounds have run, unless its Step 4 instructions failed to load. Each round re-verifies the draft against the repository and takes time, so beyond each draft’s first round you pay only for the rounds you choose; a satisfied reviewer declines. A round run by a separate auditor is also told the number of the issue the draft replaces when the run widens one, and the decisions you made during the run. That auditor is instructed not to report the replaced issue as a duplicate, and, in any finding that argues against one of your decisions, to name that decision and the defect that justifies reopening it. That defect may be of any kind the audit grades. When confirmed defects return, PRFlow applies the issue template’s routing and decision rules before composing a repair, even when the finding supplies no remedy. For example, if those rules permit deleting a sentence or moving it to the investigation record and that resolves the finding, the brief gets no replacement incidental claim. For content the brief needs, PRFlow changes the existing statement before adding required obligations, and adds no reason clause the brief does not need. PRFlow asks you to resolve choices its drafting rules reserve for you. For example, it asks when permitted fixes build different things, neither your request nor your answers choose between them, and the choice is not left to the implementer. A non-interactive run records the question as blocked. For each finding it fixes, PRFlow searches the draft and the files the finding cites for other instances of the same defect and corrects the draft for each instance; it edits no repository file. A search that fails, is refused, returns cut-short output or has no search tool is disclosed as unverified reach. Unknown obligations stay protected by the drafting and decision rules. PRFlow then re-shows the revised version before offering another round. - Approve that exact draft with Create, which names how many must-revise findings remain unfixed, or request changes.
- Answer whether to assign the issue to yourself and, when offered, whether to start implementation. On a runner that asks several questions at once, an answer carries to later prompts until you approve; a later prompt shows it instead of asking again, and you can change it there. A question still unanswered when you approve counts as no. On a runner that asks one question at a time, these come right after you approve, and anything but yes counts as no.
- PRFlow files the issue without assigning anyone, then acts on your answers. It asks nothing after filing.
Understanding the Audit Summary
The audit summary is one line. It shows how many audit rounds ran (withno verdict when the latest round gave none), the latest verdict round’s must-revise, advisory and invalid counts, how many must-revise findings were not fixed (unavailable when rounds ran but none gave a verdict), and whether the final bytes were audited. A round only counts toward a verdict when the auditor returns a FILE or REVISE verdict and names the exact draft it read.
final bytes audited means the draft PRFlow will post is byte-for-byte the draft the auditor of the latest verdict round read. Every other case reads final bytes NOT audited: an unavailable digest, no verdict round yet (with no round run at all, the line reads Fresh-context audit: not run; final bytes NOT audited), a draft body whose bytes differ from what that round read, or a draft that was never saved to a file. When preparation is finished, the draft was saved to a file and the line reads final bytes NOT audited, an interactive run whose Step 4 instructions loaded offers another round, however many have run; the summary and the filing question count and number rounds across the whole run, a redraft’s first round included. The title is outside that check. A round run without a subagent is marked degraded. PRFlow also quotes verbatim each finding of the latest verdict round it did not fix, with its grade. A finding against text that a redraft for a different option replaced counts as fixed, so it is neither quoted nor counted as unfixed.
Interactive filing still requires your explicit approval. After posting, PRFlow reports whether the stored body matches the approved draft, or that it did not compare them.
Non-interactive Filing
After preparation, a non-interactive run runs each saved draft’s first audit round and no other. With its Step 4 instructions successfully loaded, it presents the full draft and can elect Create only when preparation is finished, the unresolved must-revise count is zero or unavailable because no round has returned a verdict, no must-revise finding it graded from the latest round is left unfixed, and its latest acceptance-criteria parser run read the criteria. Such a run accepts neither assignment nor an implementation offer. If Step 4 instructions fail to load, the fallback requires explicit approval; it does not inherit this self-election route. These conditions concern filing an issue, not permission to choose unknown requirements or exclude requested work.Dependencies and Blockers
These are two different sections and they mean different things.## Dependencies lists open prerequisite issues as Blocked by #N. The implement workflow reads those declarations and stops while a prerequisite is still open, or when it cannot establish whether it is open. It recognizes prerequisite phrasing — depends on, blocked by, a line-leading After #N — wherever it appears, not only under this heading, so reserve that wording for real prerequisites.
To point at a related issue that does not gate the work, record it in Technical Context as Related work: #N rather than under ## Dependencies. The neutral wording keeps an advisory reference from being read as an execution prerequisite. With the issue-template and final-outcome guidance loaded, a filed or widened issue states each agreed exclusion, and the final outcome names every out-of-scope item the body states with its already-known tracking issue or as unfiled. If either fails to load, PRFlow reports reduced coverage and that disclosure is not guaranteed. Agreeing to exclude a case does not authorize creating another issue.
## 🚫 Blocked — resolve before implementation lists unresolved product or implementation decisions. If you decline to settle a blocking decision, PRFlow records it here rather than inventing a default. Settle those before implementation starts.
An issue is implementation-ready when its Blocked section holds no unresolved decision.
Write Criteria You Want Checked
Acceptance criteria must represent every independently testable outcome in Desired Behavior before PRFlow presents the draft. A quantitative criterion includes the command or counting rule that measures it. A draft that changes a decision rule — for example a grade, route, verdict or guard — maps the rule’s outcome before and after the change for each kind of input and mode, quoting the old rule, and reads every claim about the change’s effect from that full mapping. So a claim such as “nothing else changes” must hold for every row, not just the case you asked about. Unless your request is unreadable, absent or unwritten, the issue itself states the before and after outcome only for each kind of input the change alters or reaches; the unchanged rows it does not reach go to the investigation record, though a kind of input your request names is still covered by a criterion. Unless your request is unreadable, absent or unwritten, PRFlow writes a “stays unchanged” criterion only when you ask for it or the change reaches that behavior, and even a reached guarantee that your project’s own guidance already requires of every change, such as keeping mirrored copies in step, is left to review unless you ask for it or it is unclear whether that guidance covers the case. So a preservation you need belongs in your request. A criterion states the outcome, not the mechanism that produces it, unless you ask for that mechanism itself or another surface reads it as a contract; otherwise the mechanism, even one you chose, goes in Implementation Notes. A heuristic is a rule that sorts input whose cases cannot all be listed, such as a change’s scope stated as a rule. Anywhere in the issue, PRFlow states it as its rule and which way it fails when a case is unclear, never as a pattern or a list of cases, and places its limit under the accepted-limit rule below; no check, the audit included, asks for more of its cases, except where a set’s members can all be listed and each one’s outcome is owed. Against text other than a case addition removed under the next sentence, including an addition repaired in place, a finding that any rule lists, misses or wrongly decides a case is answered by restating the rule, its failure direction or its limit, stating the case as an accepted limit, asking you, or refuting the finding because the rule already decides the case correctly, not by adding the case, unless you asked for that case or it is a missing member of a fully listable set whose outcome the rule already decides. A finding against a case PRFlow itself added in an earlier revision, to answer a finding that a case was missing, unhandled or had no outcome, is answered by removing that addition and stating the case as an accepted limit rather than patching it, unless removing it would drop a case you asked for; that addition is repaired in place under the same missing-case rule. This does not apply to text that records your answer or requested change, fixes a contradiction or a missing end condition, rewrites first-draft text, or that PRFlow cannot place or cannot tell is such an addition. When fixing a finding raises a question about how to handle a case, PRFlow’s question also offers to leave that case uncovered as a stated limit. Every limit the issue accepts, such as a case the change knowingly leaves uncovered or a decision not to change or test something, is written into an acceptance criterion as a fact about the finished change, for example “The change leavesscripts/sync.sh’s handling of empty input unchanged.”, and stated nowhere else in the issue. A decision not to test something means a check against a named case that the finished change could ship and does not; a Testing Strategy note on how the change is verified that names no such check, such as whether the implementing run replays a case, is not a limit and stays in Testing Strategy. A limit stays in the criterion covering its case; decisions not to change something or ship a named check that no criterion covers share one criterion naming each surface and the case it keeps; any other limit gets a criterion of its own. Of the issue’s text, review’s verdict and grading rules read only the acceptance criteria. A limit written there keeps a generated checklist claim from failing on a counterexample lying wholly inside the case it accepts, though a claim quoting the change’s own text still fails when that text asserts more than the case allows, and a reviewer’s own finding can still raise the case. Covering that case later is a scope change: amend the issue first. Potential Gotchas hold pitfalls and warnings; an action the implementation must take that no existing rule already requires goes in Desired Behavior and a criterion.
A criterion that lists existing members of a set, for example every file that reads a value, marks the list at minimum unless PRFlow searched the whole repository for those members and read every match. When an answer or revision changes the design, PRFlow repeats that search with the new terms or stops treating its result as complete; it never reuses the earlier result as-is.
Before deciding where a term the draft creates or redefines is defined, PRFlow searches the existing files the issue names for that term. If one of them already gives the term a different meaning, the draft treats it as a term the change redefines, or uses a different word. PRFlow names in chat any such file it could not read or fully search.
This matters beyond the draft: the acceptance criteria are what an implement run verifies at the end. An issue with no criteria gets a run with nothing to check at that gate. See Implement an Issue.
Widening an Existing Issue
PRFlow searches open-issue titles and bodies for related mechanisms, then reads candidate issues. For an issue you ask it to refine, it also checks cross-references and the relevant issues’ current state. Missing or incomplete evidence is disclosed without discarding successful reads; a reference alone adds no scope or permission to edit another issue. PRFlow widens an open issue only when your request names it or you choose it from the duplicate check. A non-interactive run never widens an issue you did not name; if it files a new issue, it names the suspected duplicate in its outcome. An interactive widen asks approval to replace the named issue’s title and body. After the filing election, PRFlow replaces both in one request; criteria belong in the body, not a comment. Its outcome reports whether the stored title and body match the approved draft, or that it did not compare them. It then applies thePRFlow label, tries to register the new body’s ## Dependencies as blocked-by links and reports failures, and posts the investigation record, as it does for a new issue. Links declared only by the old body remain and are disclosed.
A widen treats the existing body as your request: the refined issue keeps its requirements, but PRFlow may reword its criteria or merge duplicates into new ones. To keep exact wording, say so during the run; PRFlow then asks before changing it.
A widen asks the same assignment and implementation questions as a new issue.