--- name: legion-pr-write description: | Compose the PR body as a forcing function before opening a PR. Map each of the issue's acceptance criteria to the change that satisfies it -- in your own prose, with evidence -- and state what you deliberately did NOT do. Articulation is verification: writing the mapping makes you re-read your own diff as a reader and catch what you talked past while coding. Validate the body with `legion pr write-check`, which refuses an empty or boilerplate mapping and records the gate `legion pr create` requires. Run this after `/legion-simplify`, before review. version: 1.0.0 user-invocable: true allowed-tools: Bash, Read, Write --- # Legion PR-Write The step between simplify and review. You write the PR body that maps the issue's acceptance criteria to your change, then validate it. The body you produce is the claim set the verify gate (#520) and the human reviewer read -- so write it for a reader who has not seen your work. `legion pr create` will not open the PR until this gate is clean on HEAD (alongside the simplify gate). ## Procedure 1. **Load the acceptance criteria.** You are mapping against the issue, not your memory of it: ```bash legion issue view --repo --number ``` Note every item under "Acceptance criteria". You will write one mapping entry per item. 2. **Re-read your own diff.** `git diff main..HEAD`. For each acceptance criterion, find the hunk that satisfies it. If you cannot point to one, the criterion is not met -- stop and finish the work (or move it to "Not done" with a reason). 3. **Write the body to a file** (e.g. `/tmp/pr-body-.md`) with exactly these sections: ```markdown ## Summary One paragraph: what the change does and why. ## Acceptance criteria mapping ### 1. Prose: which change satisfies this criterion and how. Explain the mechanism -- do not restate the criterion. This is the forcing function; write it as an explanation. Evidence: ### 2. ... ## Not done What you deliberately left out of scope, and why. Write "nothing" only if that is true. ``` One `### ` entry per acceptance criterion. Each entry needs real explanatory prose and a line of evidence. The mapping must be composed prose, not a checklist -- a fill-in form defeats the purpose. 4. **Validate.** This records the gate and refuses boilerplate: ```bash legion pr write-check --repo --issue --body-file /tmp/pr-body-.md ``` - Clean -> the gate is recorded; proceed to open the PR. - Gaps reported -> fix the body (each gap names the entry and what is missing) and re-run. Do not pad to clear the word count; write the real explanation. If a criterion genuinely is not addressed, that is a signal the work is not done. 5. **Open the PR** with the validated body: ```bash legion pr create --repo --title "(#): " \ --body "$(cat /tmp/pr-body-.md)" --task ``` ## Notes - The validator checks structure, not prose quality: one substantive entry per criterion, each citing evidence, plus a non-empty "Not done" section. It cannot tell a good explanation from a mediocre one -- that is your job and the reviewer's. It can tell when you pasted the criteria back, and it will refuse. - If you commit again after a clean gate, the gate no longer matches HEAD -- re-run step 4. - Re-running write-check overwrites the previous gate row for HEAD; the most recent wins. - Bootstrap only: a branch that ships these skills themselves cannot gate on them. Use `legion pr create --skip-gates` (it writes an audit row so the skip is never silent).