How do I create a PR?

Question
Answer
Conventions
Script
Tested by
See also

The body content should be assembled via How do I generate a PR summary? before running the gh command here.

Question

How do I open a pull request from my current feature branch, with a correctly-formatted title and a structured body?

Answer

Create the PR with compass pr create. It validates the title convention, assembles the body (Summary, Changes, and the ## Traceability table derived from the branch's task and story docs), pushes the branch, opens the PR, records it on the task (#+pr: and the * PRs table), commits and pushes that record, and stamps the session journal:
```
./compass.sh pr create --title "[component] One-line description" \
  --summary "What changes, why." \
  --change "First change" --change "Second change"
```
Use --draft for a draft PR and --task <uuid-or-slug> when the branch carries more than one task.
Confirm the PR URL it prints. There is nothing else to do — the task-doc record is already committed and pushed.

Conventions

PR body is Markdown, not org-mode. GitHub renders the body as Markdown; use **bold**, `code`, [text](url) etc. — never [[id:...]] links, #+begin_src blocks, or other org syntax.
No "Test plan" section in the body.
Title format is [COMPONENT] Description. Multi-component PRs use [a,b,c].
Body sections may be expanded (Notes, Decisions, Follow-ups), but Summary and Changes are the load-bearing pair.
Captures section (optional): the captures you filed while working — a bug, limitation, or idea noticed in passing and recorded with compass capture (it lands in the product-backlog inbox, not as a story task). List one Markdown link per line to each capture's published page, so what you deferred is traceable from the PR. The same un-assigned captures also surface in the sprint's * Captures section. Place it just before Traceability. compass pr create does not yet generate this section — add it by hand (or via =–summary=/body editing) until it does.
Traceability section goes at the end of the body, always. It is a Markdown table with three columns — Artefact, Link, ID — and one row per tracked artefact (Story, Task). The Link cell contains a markdown hyperlink to the published HTML page; the ID cell contains the full UUID as read from the :ID: property of the .org file. Never abbreviate the UUID to just the first segment.
Story and task page URLs follow the pattern: https://orestudio.github.io/OreStudio/<path-without-extension>.html where <path> is the file path relative to the repo root:
- Story: doc/agile/versions/v0/sprint_<NN>/<STORY_SLUG>/story
- Task: doc/agile/versions/v0/sprint_<NN>/<STORY_SLUG>/task_<TASK_SLUG>
Traceability is forward-only: add it to new PRs; do not back-fill old ones.

Script

compass pr create (projects/ores.compass/src/compass_pr.py) wrapping gh pr create. The gh CLI must be authenticated (gh auth login) once per checkout.

Tested by

Manual. Reviewers verify the PR shape; compass pr checks reports CI.