Story: Track PRs per task and surface them in compass where
Table of Contents
This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Every task document carries a * PRs table listing the pull requests
raised for that task (number and title). When a PR is created, it is
recorded there immediately. compass where --prs (part of the Locate
pillar) shows the same data live — fetching open and closed PR status
via gh — so a session can orient itself without manually checking
GitHub. Story and task UUIDs are embedded in the PR body on creation
for forward traceability.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 18 |
| Now | Completed 2026-05-24. |
| Waiting on | Nothing. |
| Next | None. |
| Last touched | 2026-05-24 |
Acceptance
v2_doc_task.org.mustachehas a* PRssection with an empty| PR | Title |table.how_do_i_create_a_pr.orginstructs the author to record the PR number and title in the task's* PRstable immediately after raising, and to include the story and task:ID:UUIDs in the PR body.compass wherelists the current version, sprint, and all STARTED stories and tasks with their file paths and UUIDs.compass where --prsadditionally reads each task's* PRstable and fetches live status for all listed PRs (open and closed) viagh pr view.- Output is available in
pretty(human) andjson(tooling) formats.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Task: Add PRs table to task template and update PR recipe | DONE | 2026-05-24 | 2026-05-24 | Update v2_doc_task.org.mustache to include a * PRs table; update how_do_i_create_a_pr.org to record PRs and embed UUIDs. |
| Task: Implement compass where with –prs flag | DONE | 2026-05-24 | 2026-05-24 | Add the where subcommand to compass.py: current version/sprint, STARTED items, and –prs flag fetching PR status via gh. |
Decisions
- PRs table on tasks only, not stories. Stories span many tasks and many PRs; the task is the unit that owns a PR. Aggregation can happen at read time (compass walks task files).
- No status column in the PRs table. Maintaining it would require
manual updates after each PR state change. compass fetches live
status from
ghinstead. - Story + task UUID in PR body, not title. Titles are read by humans at a glance; UUIDs belong in the body where tooling can parse them.
- compass where reads the filesystem directly. The cached FTS index
is for search; for
where, walkingdoc/agile/versions/and parsing#+todo:+ the Status table is fast enough and always fresh.
Out of scope
- Retroactive: existing tasks and PRs are not back-filled.
- Closed PR bodies are not parsed for UUID linkage.
compass wheredoes not mutate any state.