# Task items

<!-- squads:managed — regenerated by `sq sync`; do not edit by hand. -->
<!-- squads:version:0.5.0 -->

A unit of implementation work. Its parent is the feature it implements; subtasks each map to one user story.

**Lifecycle:** Draft → Ready → InProgress → InReview → Done (+ Blocked, Cancelled)

## Commands

```bash
sq create task "…" --author tech-lead --parent FEAT-…
sq task <n> add-subtask "…" --story US1
sq task <n> subtask <k> update --status InProgress   # Todo → InProgress → Done
sq task <n> ref add BUG-… --kind fixes   # or REV-… --kind addresses
sq task <n> status InProgress
```

## For Olivia Lead (`tech-lead`)

**Enter** — before you act:
- Read the full item dossier: `sq task <n> show --full --comments` (decisions and
  refinements often live in discussion comments, not the body — skipping this is how context
  gets missed).
- confirm the parent feature exists and its stories are clear

**Do:**
- author the task (`sq create task "…" --author tech-lead --parent FEAT-…`)
- add subtasks, each mapped to a story (`add-subtask … --story USn`) — the title is a short handle; implementation detail goes in the subtask body (`sq task <n> subtask <k> body -m …`)
- set `--priority`/`--assignee`; sequence with `ref add … --kind blocks`

**Hand off:**
- once the task is fully defined, assign the developer (`sq task <n> update --assignee <tech>-dev`) — spawn or `@<tech>-dev` to start implementation

**Watch for:**
- a task's parent must be a feature; link bugs/reviews via refs, never as parent

## For developers

**Enter** — before you act:
- Read the full item dossier: `sq task <n> show --full --comments` (decisions and
  refinements often live in discussion comments, not the body — skipping this is how context
  gets missed).
- read the parent feature's stories + acceptance criteria (`sq feature <n> show`)
- confirm your subtask→story mapping

**Do:**
- `sq task <n> status InProgress`
- implement with tests; tick subtasks (`subtask <k> update --status …`)
- use `sq task <n> subtask <k> comment` for implementation notes scoped to one subtask; use `sq task <n> comment` for handoffs and cross-cutting notes (see the `squads` skill's comment-scoping convention)

**Hand off:**
- when implementation is complete, `sq task <n> status InReview`
- comment a summary of what changed + `@reviewer`/`@qa`
- for a review follow-up, link it (`ref add REV-… --kind addresses`)

**Watch for:**
- don't author features/tasks — that's the product-owner/tech-lead
- file a newly-found defect as a bug; don't silently expand scope

## For Paul Reviewer (`reviewer`)

**Enter** — before you act:
- Read the full item dossier: `sq task <n> show --full --comments` (decisions and
  refinements often live in discussion comments, not the body — skipping this is how context
  gets missed).
- read the task's changes + the linked feature stories

**Do:**
- open a review (`sq create review … --author reviewer`) and link it (`sq task <n> ref add REV-… --kind addresses`)
- log findings with `--severity`; drive Requested → InReview → verdict

**Hand off:**
- on ChangesRequested, `@<tech>-dev` with the findings
- on Approved, comment the verdict so the task can close

**Watch for:**
- request changes — don't fix the code yourself

## For Mara Tester (`qa`)

**Enter** — before you act:
- Read the full item dossier: `sq task <n> show --full --comments` (decisions and
  refinements often live in discussion comments, not the body — skipping this is how context
  gets missed).
- derive test cases from the parent feature's stories + acceptance criteria

**Do:**
- verify the implementation against each story; reproduce on failure

**Hand off:**
- on pass, comment confirmation so the task can reach Done
- on fail, file a bug (`sq create bug …`) and `@<tech>-dev`

**Watch for:**
- verify against acceptance criteria, not just that it runs

---
The `.md` files are sq-managed — never edit them by hand. Items are addressed as
`sq task <n> <verb>`. Set this item's body with `sq task <n> body
-m "…"` (or `--file`); `--desc` sets only the short summary. Its user stories / subtasks / findings
get their bodies from `sq task <n> <kind> <k> body -m "…"`. Read anything back with
`sq task <n> show --full --comments` (full dossier, including discussion) /
`sq task <n> <kind> <k> show`.
