# Sub-tasks and relations

Break a card into smaller cards with sub-tasks, and link cards that depend on each other with relations. A sub-task is
a full card with its own key, column, recipe, owner and runs. A relation says one card blocks another, duplicates it,
or is related to it, and a blocked card waits for its blocker before it runs.

## Add a sub-task

Open the card, then any of these:

- Press `S`, or click **Sub-task**, and type the new sub-task's title.
- From the ⋯ menu, choose **Make it a sub-task of…** to put this card under another one. The card's **Sub-task of…**
  button does the same.
- On the board, hold **⌥ (Alt)** while you drop a card onto the middle of another card. The target says *Make it a
  sub-task of WEB-1*, or why it can't, and the toast offers Undo.

You can nest, promote and add sub-tasks only under cards you own. A tree is at most three levels deep: a card, its
sub-task, and that sub-task's own. Both cards must be in the same team tree.

### What a parent card shows

- On its face: *3 of 5 done*.
- In the card: the **Sub-tasks** list with each one's state or column, and **Promote** on each to make it a card of
  its own again. A sub-task shows *Sub-task of WEB-1* with its own **Promote**.
- **Done when all sub-tasks are done**: turn it on and the parent moves to Done by itself once every sub-task that
  isn't archived is in Done. It is off by default.

Nothing starts a sub-task because of its parent. It runs when someone moves it into Working, like any card. A parent
whose sub-tasks wait for each other and start on their own is a workstream instead: see
[Workstreams](https://andon-docs.pages.dev/guide/workstreams.md).

## Drag a card onto another card

What a drop onto another card does depends on what you hold:

| You hold | The drop |
| --- | --- |
| nothing | moves the card: it reorders, or changes column |
| **⌥ (Alt)** | makes it a sub-task of the target |
| **⇧ (Shift)**, in the same column | groups the two cards into one pull request at once |
| still for 600 ms over the target, in the same column | groups them; until then the target says *Hold to group with WEB-1* |

A drop into another column never groups. A group builds its cards together: one branch, one pull request.

## Add a relation

1. Open the card and press `B`, or click **Relation**.
2. Pick the kind: **Blocked by**, **Blocks**, **Duplicate of** or **Related**.
3. Search for the other card by key or title, and pick it.

Each relation shows as a chip with the other card's key, title and column, struck through when it is done.

| Kind | What it does |
| --- | --- |
| **Blocked by** / **Blocks** | holds the blocked card until its blocker is done (below). Imports from Linear and Jira bring these too |
| **Duplicate of** | the original lists this card under *Duplicates*. **Mark as duplicate…** in the ⋯ menu also archives this card, with Undo |
| **Related** | shown on both cards |

Two cards can have only one Related link between them, a card can duplicate at most one other card, and blocks
can't form a loop. For **Blocked by** and **Blocks**, the owner of the blocked card adds and removes the relation; for
the others, the owner of the card you added it from removes it. A blocker in a team you can't see shows as *A card
you can't see*.

## Blocked cards wait

A card blocked by a card that isn't done shows *Blocked by WEB-7* on its face. If you move it into Working, it waits until the blocker is in Done, then starts by itself. A plain sub-task waits the same way.

This is on by default. To change it for a team, search Settings for **Blocked cards wait** and pick the team. When you turn it off, cards that were waiting start right away, and a blocked card starts as soon as you move it
into Working.

### Blocking a card that is already in Working

If you add *Blocked by* to a card in Working that has no run going, the card moves back to the Backlog and leaves
Needs you. Its timeline says *Parked: moved to Backlog until WEB-7 lands*. Move it back into Working once it can go on.

A card with a run going stays where it is. This doesn't apply to a team whose blocked cards don't wait, a workstream
step, or a card in an open pull request group.

A run can park its own card this way: when its report says it is parked and names the cards it waits for, those cards
become the card's *Blocked by*.

## Keyboard

In an open card:

| Key | Does |
| --- | --- |
| `S` | add a sub-task |
| `B` | add a relation |

## Sub-tasks and relations in a run

A run sees a card's parent, sub-tasks and blockers only when its recipe's template asks for them with
`{{card_context}}`. See [Writing a recipe](https://andon-docs.pages.dev/guide/writing-a-recipe.md).
