Story: Clean up the compass work lifecycle
Table of Contents
This page documents a story in Sprint 20. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Backlog refinement can create stories and tasks without any branch
side-effects, and picking up work is an explicit, separate act. Today
story new and task new always couple scaffolding with branch creation,
while the add primitives do not wire #+branch — so task start later
fails without --branch. After this story: creating a story/task
scaffolds docs only; picking one up creates the branch, marks STARTED,
and stamps the journal.
The skill-side counterpart (separate create and pick-up skills) is owned by the sibling story Action-oriented skill cleanup in the same epic.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 20 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-06-06 |
Acceptance
- Creating a story or task via compass scaffolds documents only — no branch is created and no journal entry is stamped.
- Picking up a story or task creates (or switches to) the branch, marks the task STARTED, and stamps the journal in one step.
task startworks on any task created by compass without needing a manual--branchflag.- Recipes and runbooks that reference
story new/task new/addare updated to describe the create vs pick-up split.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Distinguish creating stories and tasks from picking them up | DONE | 2026-06-06 | 2026-06-06 | Make the create vs pick-up distinction first-class in compass: creating a story/task scaffolds docs only; picking one up creates the branch, marks STARTED, and stamps the journal. |
| Design a clean PR close-out workflow | DONE | 2026-06-06 | 2026-06-06 | Brainstorm and document a clean work-lifecycle so bookkeeping never needs its own PR. Candidate rules: every story gets a scaffold task, so scaffolding PRs close the scaffold task instead of wrongly closing the first real task; bookkeeping (task DONE, story and sprint sync, Result) always ends the review round and rides the PR before merge; pr merge never closes a task whose deliverable the PR does not contain (–keep-open semantics by default for non-deliverable PRs). Motivated by PR 1111, where the scaffold PR auto-closed the unstarted naming-convention task and the fix needed a follow-up PR. |
| Fix pr merge close-out bugs | DONE | 2026-06-06 | 2026-06-06 | Two bugs seen merging PR 1111: (1) the close-out commit guard string-matches 'nothing to commit', but with unrelated unstaged changes (e.g. vcpkg submodule pointer) git says 'no changes added to commit', so compass aborts before calling gh pr merge; (2) the close-out push races GitHub's merge API, which rejects with 'Base branch was modified' — needs a retry. Make the close-out commit detection robust (use git status –porcelain or check staged paths, not message text) and retry the merge on the transient GraphQL error. |
Decisions
- Create vs pick-up:
compass add story/taskscaffolds docs only;compass task startpicks up (branch + STARTED + journal) and derivesfeature/<slug-kebab>for branchless tasks. - Every new story gets an automatic scaffold task that owns the
branch and is clocked on by
story new; the first real task is born BACKLOG and unbranched. Scaffold PRs close scaffold tasks. - Bookkeeping ends the review round and rides the PR:
task done+ Result + story/sprint sync are committed on the PR branch before merging.pr mergenever touches task state — a STARTED task only draws a warning — and--keep-openis gone. - Rejected: opt-in scaffold-task flag (relies on remembering), taskless scaffold PRs (breaks traceability), close-on-merge with confirmation (prompts do not compose into skills).