Document type: task

Table of Contents

This page defines the task document type — one entry in the document types taxonomy. The general contract every document follows (frontmatter, state, linking, tags) lives on the taxonomy page; this page carries only what is specific to task.

1. Contract

Implements
loading, declaration, recording. See Regulatory Functions.
Path
versions/<v>/<sprint>/<story>/task_<task_slug>.org — a flat file inside the story folder, not a subfolder. Tasks are leaves; only composition nodes (story, sprint, version) get folders. The task_ prefix sorts tasks together (after story.org) and makes their type obvious in ls.
Title
Task: <human readable title>. The Task: = prefix is added by the codegen automatically when the type is =task.
Level
s1
Size constraint
one PR; soft limits ≤ ~10 files changed, ≤ ~400 LOC delta, one coherent concept. Tasks exceeding this should be split or promoted to stories.
Supporting files
rare. When a task genuinely needs extra artefacts (screenshots, attached data), promote that single task to a folder ahead of time (<task_slug>/<task_slug>.org plus the supporting files). The default remains the flat file.
How to create
see New task in the codegen recipe.

1.1. Task frontmatter (additions on top of the standard set)

#+owner: <handle>                                ; required (=marco= today)
#+branch: <git branch the task is on>             ; required once started
#+pr: <pr number or url>                          ; set when PR is opened
#+blocked_on: <review|ci|local_build|external|none> ; required when in STARTED/BLOCKED
#+blocked_since: <YYYY-MM-DD HH:MM>               ; set when blocked_on != none
#+todo: DISCOVERED BACKLOG STARTED BLOCKED | DONE ABANDONED

These fields make in-flight work greppable:

  • grep -l "blocked_on: review" → every task waiting on review.
  • grep -l "branch: feature/foo" → which task owns feature/foo.
  • grep -lR "^\* STARTED Status\|^\* BLOCKED Status" → every in-flight task.

1.2. Task sections

Required, in this order. The blurb tells the reader what this is; the * Goal says what success looks like; the * Status table gives the operational state.

  • Blurb (one paragraph, no heading) — opens with This page documents a [[id:31C868B9-306E-4282-BA8C-07E647021B34][task]] in the [[id:<parent_id>][<parent_title>]] story.
  • * Goal — one paragraph: what user-visible-or-internal change does this task produce.
  • * Status — table; see The Status table below.
  • * Acceptance — bulleted criteria. A task is done when these all hold.
  • * Plan — transient implementation strategy. Written when the agent starts work; distilled into the parent story's * Decisions and cleared (or summarised in * Notes) when the task closes. Plans do not outlive their task.
  • * Notes — chronological log of decisions, observations, discovered work. Append-only. Most recent at the bottom, dated.
  • * Result — filled when task closes: PR link, commit hashes, follow-up tasks filed.

1.3. The Status table — state + parent link + live channel

* Status
,
,| Field        | Value                                |
,|--------------+--------------------------------------|
,| State        | STARTED                              |
,| Parent story | Currencies end-to-end |
,| Now          | Implementing the XML serialiser.     |
,| Waiting on   | Nothing.                             |
,| Next         | Add the round-trip test.             |
,| Last touched | 2026-05-21                           |

State transitions overwrite the State row (DISCOVERED / BACKLOG / STARTED / BLOCKED / DONE / ABANDONED). The row value is greppable: grep -lR "^| State .*STARTED".

For DONE and ABANDONED tasks, Now becomes a single-sentence epitaph (Completed 2024-07-12.), Waiting on / Next are None., Last touched equals the closing date.

Heartbeat rule. Every time an orchestrator or agent acts on a task, it must update the Status rows and #+updated before yielding control. Audit flags tasks in STARTED or BLOCKED whose #+updated has gone stale.

Emacs 29.3 (Org mode 9.6.15)