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, on its Shipped card, the ones completed in the period. The Work items screen holds the full queue.

Create a work item

• From an insight. The main path: open an insight you've reviewed and select Create work item in its header. Each app the change belongs to gets its own work item, and work items for several apps share an epic. Each keeps the insight as its origin. See Insights.
• From a change. Open a diary entry on the Changes screen and choose Make a work item, on the app that changed or on one that depends on what it touched. The draft carries the entry as its evidence and keeps the change as its origin.
• 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 or on the hub's work items card, opens a blank editor for work that spans elements.
• 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. In chat, ask for the two riskiest insights from last night's batch as work items. Or paste a Jira epic to draft one work item per child issue. ProvenMap asks before it creates anything, and what it creates is a Draft.
• Drafted from a document. In chat, point ProvenMap at a PRD or RFC, bound to the board or in your connected 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 beside the board and stays with you as you move between boards.

It saves as you write. Once the work item has a name and a board, the editor saves it as a Draft. After that, every change saves within a second. The footer reads Saved as a draft, or names what's missing: Name it to save it or Choose where it lands to save it. Until then nothing is stored, so closing the tab loses it.

Opening another work item, or choosing Create work item again, saves the one you're writing first. You can move between drafts without losing anything. Discard closes a work item that was never saved; Delete draft removes a saved one from the queue.

Add the elements it concerns. Click Add elements at the top of the editor and choose a row for each element. The list opens on the board you're viewing; typing searches every layer, node, connection and aspect under this root.

You can also select nodes and choose Add to work item in the toolbar, or use the ⊕ on an aspect's detail or a board-map row.

The editor groups what you add by board. Elements the work item proposes to change go under Changed on the board, context in its own app goes under In discussion, and anything from another app goes under Referenced.

One app, reference anywhere. A work item changes one app: the board it belongs to and the layers beneath it, the repository its developer works in. It can link anything else under the root as a reference.

A reference takes a note on why it's relevant, not a change. If that app needs a change too, choose Create a work item in Billing. It opens a new work item there that comes after this one. The choice appears once this one has a name. A reference is flagged stale when its board changes, like the work item's own elements.

Choose its board. Lands on names the app board the work item belongs to. It starts on the board you're viewing when that board can hold work items; otherwise the first element you add sets it. You can pick another board at any time.

Say what should happen to each. An element you haven't explained is flagged Not explained yet in its row. Choose the flag and 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 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.

Hand it off

A Draft is yours to shape and is invisible to developers. Choose Hand off to Dev in the editor's footer, hover the draft in the queue and choose it there, 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.

A work item a developer sent back with Needs clarification opens in the editor the same way, with their question above the fields. Your revision saves as you write and stays out of the developer queue; Hand off to Dev sends it back.

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 band that counts work items by stage; Flagged counts the ones drifted or in conflict. Click a number to narrow the list to it.

The search line takes a name, an anchor, a tag or a status and turns it into a filter chip; #42 finds that work item. 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.

A row's ⋯ menu sets the Type, Epic or Tag, holds Mark completed and Delete, and offers Share to Slack… and Send to Jira…. Select rows to act on a batch.

The count under the title says whether you're reading on this board or across this board tree. On the root hub, the queue always covers the whole tree.

Statuses and marks

Expand

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. A work item a comparison raised completes when a later /aspects run on its app serves the contract.

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. 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. To remove a dependency, click a card and use 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.

The grid's 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 can span app boards, and carries a name and an optional 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 epic's progress.

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. Choosing Delete epic ungroups its work items and changes nothing else. The same menu holds Send epic to Jira….

/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.

Point a work item at a decision

A work item can name the decision it records or carries out: a Decision work item names the record it produced, and a feature or refactor names the rule it serves. Choose the decision in the editor, under the epic; the detail panel then shows ADR-n, the decision's status and a link to its board, and /work-items hands the developer the same line. Set or clear it at any status. Deleting the ADR board clears it.

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. Deleting a Completed work item leaves the board as it is, since the code already has its changes. Assigned and In progress work items can't be deleted.

Attach 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.
• 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, for picking a component by name.

/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 in chat for work items drafted from it. For a Confluence or Notion page, ProvenMap 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. Nothing syncs between the two: ProvenMap never modifies the document, and when the PRD changes, the work items drafted from it stay as they are.

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, a plan the developer approves, implement, verify and resolve. The plan rests on what the code shows. The plugin reads the files the work item changes, what depends on them and the nearby tests, then the project's own rules, checks and compiled skills.

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. To resolve a work item, the developer needs recorded evidence from the project's own checks. A structural work item doesn't wait for that: the first sync that finds all its changes in code marks it Completed with the ✓, unless it has a Remove answer.

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. A caution mark on the chip means the close comment couldn't be posted; hover it to see why.

Choose Share to Slack… from a work item's row menu to post it to a channel. If your organization hasn't connected Slack, the dialog says so and Open Connectors takes you to Settings → Connectors, where an owner or admin connects it. 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 can't I delete this work item?

Assigned and In progress work items can't be deleted. A developer holds each one and resolves it from the code side. Ask the developer to release one if it's no longer needed.

What's next