mflux PR docs

Write the PR body for the current branch. The developer must approve the body before it goes to GitHub.

Inputs

• The current branch. The base branch is main.
• Optional: the PR number, if the PR is open.

Steps

1. Collect the facts. Use only these sources:
   • git log --oneline main..HEAD
   • git diff --stat main...HEAD
   • git diff main...HEAD
   • If the PR is open: gh pr view <n> --json title,body,closingIssuesReferences and gh pr checks <n>.
2. Copy .github/pull_request_template.md to tmp-PR-content.md. If tmp-PR-content.md exists, ask the developer before you replace it.
   • Add this heading as the first line: # Draft PR Content.
   • Add the line Title: below the heading. Add an empty line after it.
   • If the PR is open, put its title from step 1 after Title: .
   • If the PR is open, gh pr edit --body-file replaces the existing body. Copy each existing section and link that the template does not have into tmp-PR-content.md. Get them from the body field of step 1. If you do not copy them, ask the developer to confirm before you discard them.
3. Write the What section. Obey pr-what-prompt.md in this folder. Use the diff from step 1 if the PR is not open. Add Fixes #<n> for each linked issue.
   • If the PR is not open, write the PR title after Title: . Use one short line that names the change.
   • If the PR is open, keep its title. Change the title only if the developer asks.
4. Write the release note. Obey release-note-prompt.md in this folder.
   • Put the note on the lines below the opening fence. Do not put text on the fence line.
   • Tell the developer which PR label the PR needs.
5. Write the Verification section. List only the commands that ran, with the result of each command. If no command ran, write TODO: add the commands that you ran. Do not write a result that you did not see.
6. Do not tick the boxes in the Checklist section. The developer ticks them.
7. Examine the text that you wrote. Do not examine the template text.
   • Apply the asd-ste100 skill in STE-flavored mode.
   • Put the text that you wrote in a temporary file. Do not put the Title: line in it. Run python3 .cursor/skills/asd-ste100/scripts/ste-lint.py <file>.
   • Fix each hard violation.
8. Run the CI check on tmp-PR-content.md. Fix tmp-PR-content.md until the check passes:

   python3 - tmp-PR-content.md <<'PY'
   import re, sys
   body = open(sys.argv[1], newline="").read()
   m = re.search(r"^```release-note[ \t\r]*\n(.*?)^```[ \t\r]*$", body, re.DOTALL | re.IGNORECASE | re.MULTILINE)
   sys.exit(0 if m and m.group(1).strip() else "FAIL: no complete release-note block")
   PY

9. Ask the developer to approve the PR content:
   • Open tmp-PR-content.md in the editor. Use code tmp-PR-content.md or cursor tmp-PR-content.md. If neither command works, give the developer the file path.
   • Tell the developer to edit the file in the editor, or to ask for changes in the chat.
   • Tell the developer to write approve in the chat when the content is ready.
   • Do not continue until the developer writes approve.
10. Read tmp-PR-content.md again after the developer approves it. The developer can edit the file before approval. Do step 8 again.
    • Make sure that line 1 is # Draft PR Content and line 2 is the Title: line. Put them back if the developer moved them.
    • Make sure that the Title: line has a title. If it is empty, ask the developer for the title. Write the title after Title: in tmp-PR-content.md.
11. Send the PR content to GitHub:
    • If the PR is not open, push the branch first. Ask for permission before you push. Obey the mflux-pr skill.
    • Run this block as one command. If the PR is open, replace the last line with gh pr edit <n> --title "$title" --body-file tmp-PR-body.md.

      title="$(awk 'NR <= 2 && sub(/^Title: */, "") { print; exit }' tmp-PR-content.md)"
      awk 'NR == 1 && /^# Draft PR Content$/ { next } NR == 2 && /^Title:/ { next } { print }' tmp-PR-content.md > tmp-PR-body.md
      gh pr create --title "$title" --body-file tmp-PR-body.md

    • The shell reads the title from the file. Do not type the title into the command. Backticks and $ in a typed title run as shell code.
    • GitHub does not get the # Draft PR Content line or the Title: line. Other lines that start with Title: stay in the body.
12. Delete tmp-PR-content.md and tmp-PR-body.md.

Rules

• Do not invent facts, numbers or test results.
• Do not change the code or the commits.
• Do not use gh pr create --body or --fill. GitHub must get the body that you checked, without the two draft lines.
• Keep the regex in step 8 the same as .github/workflows/release-note.yml and _FENCE in src/mflux/release/release_notes.py.