Skip to main content
Use this guide to pick the PRFlow documentation command that matches what you need. PRFlow has seven documentation commands. One is a router that runs three of the others in sequence; the rest do one job each. Every command except the report-only mode described below can edit files (that mode writes only a report file you ask for), and none of them commits.

​
Pick a Command

Use a sync command when the documentation tree already exists. Use a bootstrap command when it is absent, empty or needs a full rebuild.

​
Run the Complete Pass

1

Run it on the branch you are about to merge

2

Watch three steps run in order

Internal developer docs first, then external docs aligned against them, then release notes. Steps one and two are each switched on or off by configuration; step three is always evaluated and does nothing when your repository has no release-notes artifacts.
3

Read the final summary and commit yourself

/prflow:docs does not commit. That is left to you, or to the implement run that called it.

​
What the Final Summary Says

Each step ends in exactly one of four outcomes, and the summary names one per step: The summary also lists the internal files added or edited, the public-doc impact list carried forward from step one, the external files added or edited and whether a release note was added or skipped, with the reason.
A failed or unestablished step is reported as itself, never rolled up into a clean pass. If a configuration read was refused rather than answered, the summary says unestablished and the step still runs, because the switches default to on. Read the summary; do not assume a run that finished did everything.

​
The Two Switches

Both affect the combined pass only. Running /prflow:docs-sync-internal or /prflow:docs-sync-external directly ignores them. The locations themselves come from docs.internal (default docs/internal/) and docs.external (default docs/external/). See Documentation and Retrospectives.

​
External Docs Need an Internal Source

/prflow:docs-bootstrap-external generates public documentation from your internal documentation. If the internal location is empty or absent, it stops and tells you to run /prflow:docs-bootstrap-internal first.
This refusal is deliberate. Without an internal source of truth, generated public guidance would be invented rather than derived, and a confidently wrong public doc is worse than a missing one.

​
Verify One Topic Without Changing Files

1

Name the topic

2

Read the report

Nothing is edited, committed or pushed. The working tree is unchanged when the run finishes, apart from the report file when you ask for one (see below).
The report names four fields:
  • Doc verdict and location — one of RELIABLE, UNRELIABLE or ABSENT, together with the internal-doc location the run resolved. It describes the internal documentation only, a wrong default in a schema or a stale code comment being reported under current behavior instead. It is returned by default and under --lead docs; a --lead code run does not return it.
  • Relevant files — the files that implement the topic, marked to show the minimum set someone must read, with file and line references for the entry points, guards and writers.
  • Current behavior — what the code actually does today, including the failure paths and non-obvious couplings you would otherwise find the hard way.
  • Not established — what the run reports it did not do or establish, with a one-clause reason each, for example a duty it skipped or could not establish, or an internal-documentation page it located but did not read in full; none when nothing qualifies. This includes, for example, a duty whose answer rests on lines that a search the run piped through head never printed, when the run neither read those lines in full nor counted the matches with nothing cut.
You can steer where the run starts. --lead docs reads the internal documentation first (from its index) before turning to the code; --lead code starts from the code and treats documentation as supporting evidence. With no --lead, the run reads documentation then code and returns the doc verdict. To keep the report as a file instead of chat text, add --report-file with a path under .prflow/tmp/, written relative (as below) or absolute. The run writes the report there, makes no other change and replies with the path alone. If it cannot write the file, it says so and returns the whole report as text.
--report-file works only with --report-only. The run refuses to start when --report-file is given without --report-only, without a path or more than once, or when the path contains a .. segment or does not resolve inside the working directory’s .prflow/tmp/.
ABSENT means no internal document covers the topic. If the documentation location itself could not be read, the run says so instead — an absence it could not establish is not an established absence.
Create an Issue runs this report-only discovery with --lead docs alongside an independent investigator of request-specific assumptions, constraints and conditional risks before drafting a ticket. Drop --report-only and the same command fixes the internal documentation it found wrong.