How do I start work on a story?

Table of Contents

This recipe covers the transition BACKLOG → STARTED for a story. It is the entry point to Sprint execution — the phase owned by System 1 in which tasks are picked up and PRs are opened. For multi-phase stories (several PRs after the first has merged), use How do I start a new feature branch phase? instead.

Question

I have a BACKLOG story in the current sprint. How do I create a branch and mark it active?

Answer

  1. Locate the story. Stories live under doc/agile/versions/v0/sprint_NN/<story>/story.org — pick the highest-numbered sprint: 

    ls doc/agile/versions/v0/ | sort | tail -5

  2. Fetch and branch from main. Always branch from the current tip of main, not from an older local copy: 

    git fetch origin main
git checkout -b feature/concise-lowercase-description origin/main

    Branch names follow feature/<3-5-word-slug> matching the story title — e.g. feature/session-history-dialog, feature/currency-domain-type.

  3. Mark the story STARTED. Open story.org and update the * Status table:
    • Change the TODO keyword on the headline from BACKLOG to STARTED.
    • Set #+owner: to the agent or person doing the work.
    • Update #+updated: to today's date (YYYY-MM-DD).
    • Fill "Now" and "Next" rows with the first task.

  4. Commit the status change on the feature branch: 

    git add doc/agile/versions/v0/sprint_NN/<story>/story.org
git commit -m "[agile] Mark <story> STARTED"

The heartbeat rule applies from this point: every agent session that touches the story must refresh the Status rows and #+updated before yielding.

Script

Bare git CLI only. No wrapper script.

Tested by

Manual. The status change is audited by System 3* as part of the sprint heartbeat audit.

See also

Emacs 29.1 (Org mode 9.6.6)