<!--
  scaffold: work-items.md
  bucket: work-management (Bucket 2)
  what belongs here: how the PA opens, updates, and closes work items.
    - The schema and required fields (defer to work-item.json).
    - Statuses, categories, priorities.
    - The opening-BEFORE-work rule (Bucket 2 rule 1).
    - The updating-at-material-change rule (Bucket 2 rule 2).
    - Do NOT hand-edit assumption — use `pa work` CLI verbs.
-->

# Work items

## Location and shape

`work/w-YYYY-MM-DD-NNN.json`. One work item per JSON file. Canonical schema: `@stravica-ai/engineering-pa-core/schema/work-item.json`.

**Required fields:** `id`, `title`, `status`, `owner`, `created`.

**JSON properties always camelCase.** Every field the PA writes.

## Statuses

`draft` → `planned` → `in-progress` → `blocked` (branch) → `done` → `archived`

- **draft** — captured but not scoped.
- **planned** — scoped, not yet in flight.
- **in-progress** — actively being worked (self or dispatched).
- **blocked** — waiting on external input; note the blocker in the item body.
- **done** — completed; kept for reference.
- **archived** — closed for good; usually after a period as `done`.

## Categories

`feature` | `bug` | `chore` | `discussion` | `research`

Category shapes how the item sorts and displays in `desk overview`. Category is a shape signal, not a priority signal.

## Priority

`0` (critical) to `3` (low). Only set explicitly when it matters — most items sit at `2` and don't need adjustment.

## Assignee (`owner`)

Values: the PA name (self), the operator name, a role name (e.g. `librarian`), or a concrete agent name.

## Opening BEFORE work

Every non-trivial task the operator hands you gets a work item BEFORE you start executing or dispatching. No exceptions. If you catch yourself reaching for `Edit` / `Write` / `Bash` on the operator's behalf without a work item — stop. That is the signal you have slipped into the wrong mode.

"Trivial" is narrowly defined: a single one-line edit, a single file read, a status check. Everything else opens a work item first.

## Updating at material change

Update work item status at every material state change — not batched at session end. `in-progress` → `blocked` when the blocker appears. `blocked` → `in-progress` when it clears. `in-progress` → `done` when it ships.

Update the item body with links to relevant PRs, commits, or spawn-log entries.

## Do NOT hand-edit

Use `pa work` CLI verbs. `pa work create`, `pa work status`, `pa work list`. Direct edits to the JSON risk desyncing the item from the desk overview cache.

## Related

- `pa work --help` — canonical CLI reference.
- `desk work` — read-only listing.
- `packages/core/schema/work-item.json` — schema.