Work items

A work item is a change you author on the board, anchored to the elements it concerns, handed off to developers, and verified against the code when it comes back. It records why the change should happen and what must become true, then collects delivery evidence as the work progresses.

Work items live on an app board. The hub shows the ones waiting on you, and the Work items screen holds the full queue.

Create a work item

Every path below opens the same editor, and every work item joins the same queue. Only the prefilled context differs.

• From an insight. The main path: an analysis or /monitor produces insights, you review them, and the ones worth acting on become work items. Each work item keeps its origin. See Insights.
• From an element. Select a node and choose Create work item for this element in its toolbar. In the board map, right-click a board and choose Create work item for {name}. The work item starts anchored to what you chose.
• From the Work items screen or the hub. Create work item on the screen opens a blank editor for work that spans elements. On the hub, New work item on the work items card does the same. While an editor session is open, both read Open work item editor.
• From a board edit. On an app board, code owns structure. Adding a node, redrawing an edge or deleting an element stages the change instead of saving it. Committing your working copy files the staged edits as a Draft work item, in the Epic the commit dialog shows under Filed under. Turn on Release the plan for pickup to hand it off in the same step. Names, descriptions and layout save normally.
• Filed by a plugin. A plugin can file work it found as a Draft that waits for a person. The draft is anchored to the elements involved and linked to the insight behind it.
• Drafted in chat. Ask chat to turn the two riskiest insights from last night's batch into work items. Or paste a Jira epic to draft one work item per child issue. Chat asks before it creates anything, and what it creates is a Draft.
• Drafted from a document. Point chat at a PRD or RFC, bound to the board or in your connected Google Docs, Confluence or Notion. See Draft from a document.
• Captured from the running UI. /inspect opens your running app in a browser; the screens you pick and annotate become the work item's visual context.

Write it in the editor

One editor session makes one work item. It opens in the dock and stays with you as you move between boards; the top bar reads Recording work item while it is open.

Add the elements it concerns. Click the ⊕ on any element, board-map row or aspect row, on any board. The editor groups what you add by board, in two kinds. Elements the work item proposes to change go under Changed on the board, and context nobody is asked to touch goes under In discussion. The crosshair beside a board is the depth dial: it limits what you can add to that board and the layers under it.

Say what should happen to each. The editor asks a question per element, such as "What should happen to Billing API?". Answer Change behavior, Add capability, Fix an issue, Remove or Investigate, and add a note. The editor composes the developer's instructions from these answers, grouped by answer, and previews them under What the implementer will read.

Name it and say why. A work item carries four parts:

Every work item also has a number such as #42, the handle for PR titles and conversation. Numbers are unique in the workspace and never reused. Priority and effort come from the insight a work item was created from and show as badges.

Pick a type. Every work item is one of five types, set in the editor or from the row's Type menu at any time. The type says what a good work item of that kind has to state.

A developer's gap review checks the work item against the same table, so a work item that misses it comes back as Needs clarification instead of being guessed at. A Decision, once made, usually becomes a decision board; the work item is the work of deciding.

Hand it off

A Draft is yours to shape and is invisible to developers. Hover it in the queue and choose Hand off to Dev, or select several and hand them off from the bulk bar. Handing off locks the work item and makes it visible to /work-items pulls; its status becomes Open.

The author hands off their own drafts. An organization owner or admin, or the board's owner, can hand off anyone's, and only they can assign a work item to specific people.

Track the queue

The Work items screen opens on a summary of the plan. A band across the top counts Draft, Handed off, In progress and Completed work items, with who holds each. The completed count also says how many a sync has confirmed.

Three more stages, Needs clarification, Declined and Resolved, appear when something is in them. The Flagged number counts the work items that are drifted or in conflict. Click a number to narrow the list to it; click again to clear.

Under the band, a single line handles search and filtering. Type a name, an anchor, a tag or a status, then pick a value to turn it into a filter chip. #42 finds that work item. The View menu groups and sorts the list. Epics, beside it, groups the list by epic in one click, and the toggle at the end switches to the grid.

Grouped by status, the default, the list leads with Needs you: drafts to hand off, questions from developers, and live work items that drifted or conflict. Each row shows the number, type, name, one line on where it stands, and the elements it touches, with its epic and tags at the right.

The row's ⋯ menu sets the Type, Epic or Tag, offers Share to Slack… and Send to Jira… when those are connected, and holds Mark completed and Delete. Select rows to hand off, file under an epic, retype, tag or delete a batch.

The count under the title says which scope you are reading, on this board or across this board tree, with a link to switch. On the root hub, the queue always covers the whole tree. Click a row to open the work item in the editor dock; there is no separate detail page.

Statuses and marks

Expand

If the next sync finds that an Open or Assigned structural work item's changes already exist in code, the work item completes itself.

Three marks can appear beside a status:

• ≠ Drifted: the anchors moved after the work item was written. Review it before anyone builds against an outdated board.
• In conflict: another work item changes the same element. Decide which one goes first, usually by deleting or re-scoping the other.
• ✓ Confirmed: a sync after completion confirmed it. For a structural work item, such as one with a Remove answer, the sync checks the change in the code.

Plan the order on the grid

The grid shows the same queue as a plan. Switch from List to Grid in the view toggle.

Columns show the wave by default: how many groups of work items must finish before this one can start. Wave 1 waits on nothing; everything in wave 3 follows something in wave 2. Read left to right for the sequence. Columns can also show Phase, Status, Priority or Effort. A phase is your own ordered tag vocabulary: set the order in Settings → Context Tags, in each tag's Order field.

Rows use the list's grouping, by status unless you change it. Group by Board to read the plan down the same tree you navigate.

Drag a card onto the work item it follows to move it into the next wave. Click a card to highlight every work item before and after it, and remove a dependency from the strip above the grid. A work item can wait on several others from any board under the same root, and you can change the order at any status, even after completion. The grid refuses dependency cycles.

A drifted work item keeps its column and shows as an amber card. The grid uses the same search, filters and stage band as the list. Its state is kept in the address bar, so you can copy the link to share a plan.

Group work items into epics

An epic groups the work items that belong together: a migration, an adopted ADR's per-app work, a release. It spans app boards, so one plan can hold work on several. Give it a name and, if it helps, a Why.

Choose New epic at the top of Work items to start one before any work is in it. You can also type a new name into any epic picker and choose Create epic. A work item belongs to at most one epic. File it from the editor, the commit dialog, the row's Epic menu item, or Epic on the bulk bar for selected rows.

Click Epics to group the list by epic. Each header shows the plan's progress, such as 2 / 5 completed, and how many a sync has confirmed. An epic with no work items yet still gets a header, unless a filter is on.

Edit epic in the header menu renames it or rewrites its Why. Close an epic from the same menu when the plan is done. An epic doesn't close on its own when its work items complete. Closing it is your decision. Delete epic ungroups its work items and changes nothing else. Send epic to Jira… is in the same menu.

/adopt-adr files each decision's remediation work items under an epic named for the ADR, and a developer can pull one epic's work items alone by naming it to /work-items.

Close or delete a work item

Mark completed closes a Draft or Open work item yourself: a Task you did yourself, a Decision you recorded. Only a later sync adds the ✓. Once a developer holds a work item, completing it is up to them.

The author can complete their own draft. An organization owner or admin, or the board's owner, can complete anyone's draft or open work item. The work item's row and details say who completed it.

Delete removes the work item. The board keeps what you committed. Elements the work item added stay until the code has them too, or until you remove them. A code-owned element it removed returns at the next sync. Assigned, In progress and Completed work items can't be deleted; completed ones stay as the record of what shipped.

Attach the screen it concerns

A work item can include the screen it concerns. /inspect stores each page it captures as a page capture: a clean screenshot plus a map of its elements. In the editor's Visual context section, open Annotate capture:

• Pick component. The highlight snaps to the smallest element under your cursor and resolves to the source file it renders from, so the anchor points a developer at real code.
• Draw box. Box any region and add a note, such as "this spacing is wrong" or "make this a dropdown".
• Components. The capture's render tree sits beside the image, so you can pick a component by name rather than by pixel.

/work-items shows the developer the annotated screen, the picked components and the files behind them. Pages covers captures.

Draft from a document

Bind a PRD or RFC as a reference source, then ask chat to draft work items from it. For a Google Docs, Confluence or Notion page, chat offers to bind it first. Each work item drafted from a bound document shows a Drafted from line in its details, linked when the document has a URL.

The line records where the work item came from; nothing syncs between the two. Chat never modifies the document. When the PRD changes, the work items drafted from it stay as they are, because they are work items with their own lifecycle. The board adds what the document can't: which elements the requirement touches, and whether the code made it true.

How developers receive them

Developers pick up work in the repository with /work-items in the code plugin. It follows a fixed sequence: claim, gap review, implement, verify and resolve. The pull lists each work item's number, type and epic.

The gap review happens before any edit. When it finds a blocking gap, the developer sends the work item back as Needs clarification with a note. When the board has drifted, the plugin stops rather than build against it. A work item completes only with recorded evidence from the project's own checks.

Send to Jira and Slack

When your team tracks work in Jira, Send to Jira turns a work item or an epic into Jira issues. The issue gets a comment when the work item closes. The issue key shows as a chip on the work item's row and in its details; click it to open the issue. A caution mark on the chip means the close comment couldn't be posted; hover it to see why.

When your organization has Slack connected, choose Share to Slack… from a work item's row menu to post it to a channel. For a steady feed, a Slack automation can post the Work item needs you and Work item completed events as they happen. See Automations.

FAQ

Why did my edit on the board become a work item?

On an app board, code owns structure. Adding, redrawing or deleting an element stages the edit, and committing your working copy files it as a Draft work item for the code side to make true. The edit isn't lost, and the board doesn't treat it as true until the code makes it so.

Why can't I delete this work item?

Assigned, In progress and Completed work items can't be deleted. A developer holding one resolves it from the code side, and a completed one stays as the record of what shipped.

Why doesn't my completed work item show ✓?

The ✓ comes from a sync after completion, never from marking it completed. It appears once the next /sync runs, and for a structural work item, once that sync finds the change in the code.

Does editing the PRD update the work items drafted from it?

No. Drafted from records where a work item came from; nothing keeps the two in step.

What's next