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.
1. 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.
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 20 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-06-06 |
3. 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.
4. 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. |
5. 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).