work-items git:20260916.2afadb2A

Immutable. This exact content is served forever at /api/v1/blob/2e0b72ed7cf046a0.

---
name: work-items
description: >-
  This skill should be used when you are planning or discovering the SHAPE of a
  work item — that it breaks into sub-tasks (a parent and its parts), or that
  one piece must land before another (a blocks / blocked-by dependency) — and
  you want that structure recorded so it shows up in Kurrent Capacitor's Home
  "Blockers & dependencies" view and progress figures. Also use it at the end of
  a session or a plan step that leaves work unfinished, to record each
  unfinished piece as a loose end in the user's next-work ledger. Use the `kcap
  mcp workitems` MCP tools to DECLARE the breakdown, the relations and the loose
  ends. Do NOT declare STRUCTURE for ordinary "attach this session to issue X"
  correlation alone (a single `declare_work_item` call, no structure), or for a
  single indivisible task with no parts and no dependencies — a loose end is
  worth declaring in either case.
---

# Work items — declaring breakdown and dependencies

A work item's **breakdown** (a parent broken into parts) and its **dependencies**
(one item blocks / is blocked by another) are things you **declare** through the
`kcap mcp workitems` tools. The server never infers them — if you don't declare
the structure, the work item has an empty topology and Home renders no blockers,
no dependency graph, and no `n/m parts` progress figure for it.

Only declare structure that is **real and you are confident of**. Fabricated or
speculative parts/relations are worse than none. A single indivisible task needs
no breakdown.

## When to use these tools

- You've planned a work item as several sub-tasks → create the part items and
  declare the parent→parts breakdown.
- You know one item must be finished before another can start → declare the
  dependency.
- The structure changed (a part was dropped, a dependency no longer holds) →
  retract it.
- You want to see the current structure → read the topology.
- Two items describe the same work (a title-only item you created and the
  issue/PR-keyed item the server minted) → merge yours into the keyed one.
- The session was attached to the wrong item → detach it.
- You are ending a session, or a plan step, with work you did not finish → declare
  it as a loose end so it lands in the user's next-work ledger instead of evaporating.

## The flow

1. **Attach the session to its work item** (if it isn't already). `declare_work_item`
   with exactly one of `issue_key`, `pr_number`, `work_item_id`, or `new_title`.
   Check `get_session_work_items` first if unsure what the session is attached to.
2. **Create the part items.** Each part is itself a work item — create one per
   sub-task with `declare_work_item` (`new_title`), keeping the id each returns.
3. **Declare the breakdown.** `declare_work_breakdown` with `parent_id` and the
   `part_ids`. It is idempotent — re-declaring an existing part is accepted, not
   an error.
4. **Declare dependencies** where they exist. `declare_work_relation` with
   `from_id`, `to_id`, and `relation_kind` `"blocks"` (from_id blocks to_id) or
   `"blocked_by"` (from_id is blocked by to_id).
5. **Verify** with `get_work_item_topology` (pass the parent's `work_item_id`) —
   it returns the parent, parts, and dependencies you can see.

## Duplicates and wrong attaches

A `new_title` declare made before a PR or issue existed becomes a duplicate once the
server mints the keyed item for that work. Do not declare a breakdown to connect the
two — that records structure that isn't there. Merge instead:

- `merge_work_item` with `work_item_id` = the title-only item and `into_work_item_id` =
  the keyed item. The keyed item survives; the title item's sessions and links move to
  it. Repeating a landed merge is a no-op.
- The server refuses (409) when a user marked either item standalone, rejected the
  pairing, or the items belong to different tracker hierarchies. Stop and tell the
  user — they can merge from the dashboard. Do not retry.
- `detach_work_item` removes this session from an item it was wrongly attached to. The
  removal is durable for automated correlation; an attachment a user pinned cannot be
  removed by an agent.

## Loose ends

A loose end is one concrete piece of unfinished work — a missing test, a TODO you left in
the code, a follow-up the user asked for. Declare each with `declare_loose_end` (`text`,
one plain sentence). The server keys it on the session, the owner and the normalized text,
so declaring the same end twice is a no-op (`created: false`). It refuses text shorter than
12 or longer than 500 characters and "none"-style phrases — do not declare that there is
nothing left. Loose ends are the user's; they are never converted into work items by this
tool.

## Rules the server enforces

- **Visibility, not repository.** Every item you name must be visible to you.
  Repository is display only: a part may live in a different repository than its
  parent, and a relation may cross repositories.
- **One parent per part.** A part can belong to at most one parent breakdown.
- **No self-relation.** An item cannot block or be blocked by itself.
- **Idempotent declares.** Re-declaring an existing part or relation is fine.
- **Server-assigned attribution.** These tools take no `source`/`declared_by` —
  the server resolves the caller. Don't look for such arguments.
- **Retract, don't delete.** Use `retract_work_breakdown` / `retract_work_relation`
  when the structure changes.
- **Merges defer to user facts.** A standalone confirmation or a rejected pairing a
  user recorded blocks an agent merge; only a user can lift it.

## Tool reference

| Tool | Required args | Purpose |
|---|---|---|
| `declare_work_item` | exactly one of `issue_key` \| `pr_number` \| `work_item_id` \| `new_title` | Attach the session to a work item (or create one). `session_id` defaults to the current session. |
| `get_session_work_items` | — | List what the current session is attached to. |
| `declare_loose_end` | `text` | Record one unfinished item in the user's next-work ledger. `session_id` defaults to the current session. |
| `declare_work_breakdown` | `parent_id`, `part_ids` | Declare parent → parts. |
| `retract_work_breakdown` | `parent_id`, `part_ids` | Detach parts from the parent. |
| `declare_work_relation` | `from_id`, `to_id`, `relation_kind` (`blocks`\|`blocked_by`) | Declare a dependency. |
| `retract_work_relation` | `from_id`, `to_id`, `relation_kind` | Retract a dependency. |
| `get_work_item_topology` | `work_item_id` | Read parent, parts, and dependencies (visibility-scoped). |
| `merge_work_item` | `work_item_id`, `into_work_item_id` | Merge a duplicate into the survivor (prefer the keyed item as survivor). |
| `detach_work_item` | `work_item_id` | Detach the session from a wrongly attached item. `session_id` defaults to the current session. |

## Requirements

Requires `kcap login`. The `kcap-workitems` MCP server is auto-registered for
every supported harness by `kcap setup` and by `kcap plugin install`.