# Task management

A task is a unit of development work. Hang tasks under a story and move them across the board day to day, attaching an assignee, a priority and an estimate.

![PM on Rails board. Tasks in To do / In progress / Review / Done. Before: implementation moved and the board stayed stale. After: pull request activity returns to progress.](https://pmonrails.com/docs-img/kanban.png)

![Board video. Check the tasks in each column and the pull requests linked to them. Daily work stays under the request and acceptance criteria.](https://pmonrails.com/docs-video/kanban.webm)

## Three kinds of task

- **Work** — Internal improvements, refactoring, investigation and other work that is awkward to write as a behaviour.
- **Behaviour (scenario)** — Work you can write as Given / When / Then, in the form 'you can do X'. It maps directly onto a scenario.
- **Bug** — A defect in an existing feature. See [bugs and change management](https://pmonrails.com/en/docs/bugs-changes.md) for details.

> The kinds are deliberately limited to three so you never have to deliberate. Instead of adding kinds such as 'infrastructure work' or 'design', express those with the standalone tasks and labels described below.

## What you can attach to a single task

Open a task and you can edit the following.

![PM on Rails task edit. Estimate, assignee and due date. Before: estimates were numbers in chat. After: the work stays under the story.](https://pmonrails.com/docs-img/estimate.png)

- **Assignee** — Pick from the members of the workspace (leaving it unassigned is fine, and you can change or clear it later).
- **Priority** — Switch between four levels, low / medium / high / urgent, with colour-coded buttons.
- **Estimate** — Enter it in the project's unit (story points `pt` or hours `h`).
- **Due date** — Set a date (it also feeds delay detection).
- **Labels** — Attach free-form tags for cross-cutting grouping and filtering.
- **Description** — Notes and extra context about the work. The Given / When / Then of a scenario is edited on the scenario side.

## AI estimates (a sense of the size)

Press 'Get an AI estimate' and it proposes **a sense of the size**, taking the requirement cards, requirements and background into account.

- It returns p50 to p80 (a lean value through to one with slack) **against an average engineer** and attaches its reasoning. 'Use p50' / 'Use p80' drops the value straight into the estimate field.
- For an assignee who has built up a track record (the time from starting work to finishing it), it also gives **a value recommended for that person**.
- Note: the values are proposals. Using them is optional and the final decision is a human one (see also automatic estimates in [tracking progress](https://pmonrails.com/en/docs/progress.md)).

## Running the board (four states)

Tasks move by drag across four states: 'To do → In progress → Review → Done'.

- **By default the view is filtered to 'the current sprint'.** The view toggle at the top ('Current sprint' / 'Also show work not assigned to a development period') lets you mix in tasks with no sprint assigned (the backlog) ([tracking progress](https://pmonrails.com/en/docs/progress.md)).
- Cards are grouped by story, and each card shows the kind, priority, assignee, estimate, labels and pull request state at a glance.
- **Completion updates the parent story automatically** — Once every task underneath is finished, the parent story's status moves on by itself.
- **Link a pull request and it completes automatically** — Link a GitHub pull request to a task, and merging it moves the task to 'Done' automatically ([GitHub integration](https://pmonrails.com/en/docs/github.md)).
- **Read "In review" on two axes** — The board still has four columns, but the task detail shows **implementation status** (not started / in progress / merged) and **verification status** (not needed / waiting / satisfied) separately. When the pull request is merged but the card stays in "Review", the UI explains it as "merged, waiting for evidence", and recording a result on [Testing](https://pmonrails.com/en/docs/test-results.md) is the natural next step. On the board, cards in Review whose implementation is already merged get a subtle marker.

## Seeing the whole hierarchy (story → task → subtask)

![PM on Rails task hierarchy. Work hangs under the story. Before: you re-explained why the task existed. After: you can follow why this work is here.](https://pmonrails.com/docs-img/task-hierarchy.png)

- Open a story and you see the tasks and scenarios under it in one list.
- Add 'children' (subtasks) to any task to split a large piece of work.
- On the board, a scenario can be handled as a scenario task (a work card for 'you can do X'). The card is the anchor for implementation, pull requests and test results; the source of truth for the scenario text stays on the scenario side.
- **Standalone tasks are fine too** — Infrastructure work and the like that belongs to no story can be managed as a task on its own (directly under the project).

Just by walking the hierarchy you can tell which story something is for and how far it has got.

## Dependencies (deciding what comes first)

The task detail screen has 'Dependencies', where you can specify '**tasks that must finish first (these are prerequisites)**'. Pick them from 'Select a prerequisite task' and add them, and it becomes clear that the task is waiting until its prerequisites are done (a scenario is also a kind of task, so you specify it on the same screen). Epics on the roadmap can have their ordering set against each other from the detail panel too ([tracking progress](https://pmonrails.com/en/docs/progress.md)).

## Ready and done criteria (DoR / DoD)

Whether work may start (Definition of Ready) and whether it counts as finished (Definition of Done) are checked with **checklists**. This prevents quality gaps and the accident of starting work on something that has not been decided yet.

![PM on Rails DoR / DoD settings. Checks before start and before done. Before: 'too early / already done' depended on the person. After: missing items are visible.](https://pmonrails.com/docs-img/checklist.png)

- **The items are decided per project** — Edit the DoR / DoD items under 'Project settings > Start and completion checks' (the initial values include 'requirement cards and requirements are clear', 'a scenario exists' and 'the Given/When/Then of the scenario is concrete').
- **Tick them on the task or story edit screen** — Tick the items you have satisfied. **The required items you have not satisfied stay listed**, so what is still missing before starting or finishing is obvious.
- **They kick in when you move a card on the board** — DoR is checked when you move a card to 'In progress' and DoD when you move it to 'Done'. When something is unmet you can choose, depending on the configuration, to **show a warning** (and carry on) or to **block the move** ('Project settings > Start and completion checks').
- The judgement about whether work can start belongs at the level where hands actually move (the task or the story). The requirements phase focuses on whether something is decided (settled).

## Discussing in comments

You can leave comments on each task, which records spec questions and back-and-forth against the work they belong to. Guests (contractors and the like) can **@mention collaborators** in comments too ([Members and permissions](https://pmonrails.com/en/docs/members.md)).

## Managing and building with Claude Web, Claude Code or Codex

Tasks can be handled directly from external AI tools such as Claude Web, Claude Code and Codex ([MCP integration](https://pmonrails.com/en/docs/mcp.md)). A PM can organise and review in Claude Web while an engineer implements in Claude Code or Codex with the background in view.

### From starting work to finishing it

1. **Pick a task** — Ask it to 'start the next task' and it reads assignees, statuses, estimates and background to decide which task to start.
2. **Move the status to 'In progress'** — Starting work flips the status to 'In progress' and records **the time work started** automatically (which later becomes the actual duration → [automatic estimates](https://pmonrails.com/en/docs/progress.md)).
3. **Receive a branch name and a pull request template** — The response when work starts includes a **branch name** dedicated to that task and a **pull request trailer** (a single `PMR-Task: ...` line). Claude Code and Codex use them as-is, so nobody has to type an ID by hand.
4. **Implement with the background in view** — Because the linked requirement cards and scenarios are readable too, you can implement with 'what has to be satisfied' in mind.
5. **Merge the pull request → done automatically** — If the link exists through the branch name or the pull request trailer, merging the GitHub pull request moves the task to **'Done' automatically** and recalculates the parent story's status ([GitHub integration](https://pmonrails.com/en/docs/github.md)).

### You notice when the spec changes mid-implementation

Claude Code and Codex can detect whether the upstream requirement cards or scenarios changed after work started. If the spec changed while work was in progress, the pull request is marked as 'needs re-checking' at merge time, which prevents the accident of taking in work built against an outdated spec ([change tracking](https://pmonrails.com/en/docs/change-tracking.md)).

### The result is the same as working in the screen

Whether you update from Claude Web, Claude Code or Codex or from the screen, **the same data** changes and the same permissions and safety checks apply. Assignee, status, estimate, labels, dependencies: anything you can edit in the screen an agent can do too. For the list of tools and practical prompts see [Claude Web, Claude Code and MCP integration](https://pmonrails.com/en/docs/mcp.md).

## Next steps

- [Bugs and change management](https://pmonrails.com/en/docs/bugs-changes.md) / [Tracking progress](https://pmonrails.com/en/docs/progress.md) / [Claude Web, Claude Code and MCP integration](https://pmonrails.com/en/docs/mcp.md)

---

https://pmonrails.com/en/docs/tasks