Work a task through to merged PR

Take an existing task from BACKLOG through implementation, PR creation, review rounds, and merge — the full development lifecycle. Task/story bookkeeping happens before the PR is raised, not after review approves: the work is done as far as the developer is concerned by the time review starts, and review is a post-done validation activity. This ordering exists specifically so that once the final review round is approved, merge is the only remaining action — no bookkeeping-only commit forces another, otherwise-avoidable round. GitHub runs no check on a pull request, so the gate is the local compass check run in step 5.

• A task exists in the current sprint with #+type: task, State: BACKLOG.
• The task's story is STARTED in the sprint.
• You are on main or can create a fresh feature branch.
• gh CLI is authenticated; the session's SSH agent is used as-is (see Do not interfere with SSH session variables).

In execution order:

1. Clock on. Run compass task start with the task's slug to switch branch, mark the task STARTED, and stamp the session journal:

   ./projects/ores.compass/compass.sh task start <task-slug>
   

   A task with no #+branch: (scaffolded via compass add task or born as a story's first real task) gets feature/<slug-kebab> derived automatically, created off fresh origin/main; --branch overrides:

   ./projects/ores.compass/compass.sh task start <task-slug> --branch <override>
   

   This covers all three cases: new task on an existing story, resuming a BACKLOG task, and restarting an already-STARTED task after a session reset. Read task_<slug>.org after clocking on: understand the * Goal, * Acceptance criteria, and * Notes. (pr create sets #+pr: later.)

2. Sync with main. compass pr sync — fetch, rebase, report; on conflicts it stops with the conflicted files and the ways out. If you are on main, create a feature branch first: see How do I start work on a story?.
3. Implement. Do the actual work: write code, documents, or configuration. Follow the conventions in LLM instructions for code style, documentation, and testing.
4. Commit. Use ORE Studio commit conventions: [component] Imperative summary with a Co-Authored-By: trailer. One logical change per commit. Never amend commits on a branch under review.

5. Run the local check gate. One command classifies the change and runs the checks it needs — the build, the database and the suites included when the change reaches compiled code:

   ./compass.sh check
   

   Do not proceed until it is green. This is the only gate the change gets: GitHub runs no check on a pull request. The report at build/output/local_checks/report.md names every failure and its fix; see CI workflows and local checks.

5a. Run the local code review. The automatic GitHub review (claude-code-review.yml) is retired; the local review is the review coverage now. Run the compass-code-review-pr skill on the change, record its findings in the task's * Review table with their decisions, and address the accepted ones before raising the PR. The misspell check (misspell-fixer .; exit 0 = clean) is part of this review pass.

1. Close out task/story bookkeeping now — before the PR exists. The task is done as far as the developer is concerned; review is a post-done validation activity, not something bookkeeping waits on:

   ./projects/ores.compass/compass.sh task done <slug>
   

   Task and story row flip to DONE with end date. Write the task's * Result by hand, distill any * Plan into the parent story's * Decisions. If this was the final task in the story, update both files in the same commit:

   a. In story.org * Status: state → DONE, Now → Nothing., fill End date. b. In sprint.org * Stories: update the story row to DONE and fill End.

   Both files must stay in sync — a story DONE in story.org but STARTED=/=BACKLOG in sprint.org is a silent inconsistency the sprint health review will not catch automatically. Commit this bookkeeping now; it will be part of the PR from its very first push, not a follow-up. A task spanning several PRs stays open — close it on the PR that completes it.

2. Open a PR. compass pr create per How do I create a PR? — it pushes (bookkeeping commit included), builds the body with Traceability, records the PR on the task, and stamps the journal. Include the step-5 build/test result as an explicit --change bullet so it's visible in the PR description.
3. Watch for review comments. No check runs on the pull request, so there is nothing to wait for on the check side. If a check fails on the main push after the merge, follow How do I fix a failing local check? — the same check reproduces locally.

4. Handle review. When review comments arrive, follow How do I address PR review comments?:

   • Sync with main first (rebase).
   • Decide accept/decline per comment.
   • Apply fixes (one commit per logical fix); build and test locally before pushing.
   • Push once — fixes and this round's * Review table update together, never a separate bookkeeping-only commit afterward.
   • Reply to every comment, resolve threads (API calls, not commits — safe to do after CI is green without starting a new cycle).

   Repeat step 9 for each review round until the PR is approved.

5. Merge once the review is approved. Nothing should be pushed between the last green compass check run and the merge: task/story bookkeeping already rode in with step 6, and review- round bookkeeping already rode in with each round's fixes (step 9). The only things that legitimately delay a merge are a real merge conflict with main (rebase, re-run compass check, then merge) or a genuinely new review round.

   ./projects/ores.compass/compass.sh pr merge
   

   The guards refuse while threads are unresolved; merge never touches task state (a STARTED task is a hard stop, not a warning — see compass-pr-merge), retries GitHub's transient base-branch-modified race, and deletes the remote branch. See How do I merge a PR?.

• Task is DONE with * Result filled, and the close-out commit rode in with the first push of the PR, not a late one.
• PR is merged into main with no commits after the last green compass check run other than genuine review-round fixes or a rebase.
• Review rounds are recorded in the task's * Review table, each entry committed together with that round's fixes.
• Parent story reflects any decisions from the task's * Plan.
• If the story is complete: story.org and sprint.org both show DONE with matching end dates.

• How do I start work on a story? — branch creation and STARTED transition.
• CI workflows and local checks — the decision tree and the check catalogue the step-5 gate uses.
• How do I monitor a PR until green? — the review waiting loop, now that no check runs on a pull request.
• How do I merge a PR? — close it out.
• Start work on a new story — the preceding runbook for the story-scaffold phase.
• Runbook glossary entry — what a runbook is and how to create one.