How do I work a task?
Table of Contents
A task is a PR-sized unit of work inside a story. Tasks share the story's feature branch — they do not get their own branches. For the story-level branch-and-status recipe, see How do I start work on a story?.
Question
How do I pick up a task, record progress, and close it when the work is done?
Answer
Picking up a task (BACKLOG → STARTED)
- Open the task's
.orgfile underdoc/agile/versions/v0/sprint_NN/<story>/task_<slug>.org. - Update the
* Statustable:- Change
StatefromBACKLOGtoSTARTED. - Set
Nowto a one-line description of the first action. - Set
Nextto whatever follows the first action. - Update
Last touchedto today.
- Change
- Fill in
* Planif it is still the placeholder text. The plan is the implementation strategy — keep it short (bullet list, not prose). It is transient: distil key decisions into the parent story's* Decisionswhen the task closes, then clear it. Commit the status change on the story's feature branch:
git add doc/agile/versions/v0/sprint_NN/<story>/task_<slug>.org git commit -m "[agile] Mark task <slug> STARTED"
During execution
- Append findings, decisions, and blockers to
* Notesas they occur — one bullet per entry, newest last. - Update
Now/Next/Last touchedwhenever the task changes direction. These fields are the live status; keep them current. - If the task becomes blocked, set
StatetoBLOCKED, fillWaiting onandBlocked since, and commit.
Closing a task (STARTED → DONE)
- Write the
* Resultsection: what was built, what was verified, any gotchas a future reader needs. Factual and durable — no PR numbers (the git log has those). - Update
* Status:- Change
StatetoDONE. - Clear
Now/Waiting on/Next. - Update
Last touchedto today.
- Change
- Distil any plan decisions worth keeping into the parent story's
* Decisionssection, then clear* Planin this file. Commit:
git add doc/agile/versions/v0/sprint_NN/<story>/task_<slug>.org \ doc/agile/versions/v0/sprint_NN/<story>/story.org git commit -m "[agile] Close task <slug>"
Abandoning a task (→ ABANDONED)
Set State to ABANDONED, add a one-line reason in * Notes, and
commit. Do not delete the file — the history is useful.
Script
No script — pure status-table edits on the task and story files.
Tested by
Manual. Applied to every task in Sprint 18 and later.
See also
- How do I start work on a story? — story-level branch creation and BACKLOG→STARTED transition.
- Add a task to an existing story — runbook for scaffolding a new
task into a story with
compass add task. - Task — the document type contract.
- Document types — full frontmatter contract and TODO vocabulary.
- Lifecycle — TODO state machine for all stateful doc types.