Work items
A work item brings together the issues, PRs, commits, and recorded sessions behind one effort. Use Work Items in the sidebar to follow that effort from planning through implementation and review.
Browse work
Section titled “Browse work”The list shows each item’s title, repository, tracker links, session activity, and available evaluation information. Use the filters to choose All, In flight, Shipped, Closed, Duplicates, or Resolved.
These labels describe different things. Shipped and closed reflect the work’s linked delivery and tracker state. A duplicate is an item merged into another item; it is kept for history. Resolved items record work that was split into other items.
Open a card to visit its detail page. The URL identifies the item, so you can return to it or share it with someone who has access.
Read a work item
Section titled “Read a work item”| Tab | What to look for |
|---|---|
| Overview | Current state, who’s working on what, suggested follow-up, parts, blocking relationships, and the declared plan. |
| Activity | Attached sessions and milestones across the work. |
| Links | Shipped and still-open issue/PR links, commits, and incidental references. |
| Retrospective | Evaluation coverage, recurring findings, strengths, suggestions, and spend. |
A passing mention of another ticket can appear under Also referenced without being treated as this item’s main issue.
When an agent declared a plan for the work, Plan on Overview shows its task list, eight rows at a time. Tasks declared in sessions you cannot see are left out, and the card says when the list may be incomplete. See Session outcomes for how agents record plans.
The retrospective includes copy and slide-deck export controls when results are available. Use them to share findings, then open the source sessions when you need the evidence.
How sessions attach
Section titled “How sessions attach”A session is filed only by the work it did. Continuation chains keep related session segments together. Optional AI correlation handles cases where references alone are insufficient; administrators configure its scope under Work items settings.
| Evidence | Effect |
|---|---|
A commit naming the ticket in its title, after Fixes or Closes, in a Refs:, Linear:, or Issue: line, or as a trailing (#123) PR number | Files the session on its own. |
| The session’s opening message, the branch it ended on, or a PR it checked out, merged, reviewed, commented on, or edited | A hint for AI correlation. |
| A PR the agent only viewed, a branch it passed through, or a ticket mentioned in passing | A mention only; it never files the session. |
In a code-review session, the PR being reviewed is the work, so reading it counts. Without a connected Linear workspace, a branch word counts as a ticket only when your team’s commits already use that prefix.
A commit is credited to the repository git recorded it in, so fixes #45 made after cd into another repository links that repository’s issue. Where kcap has only the typed command to go on, it no longer guesses what a bare #45 refers to after a folder change.
Clearing a chat starts a new session that inherits nothing from the one before it. It stays unfiled until its own work files it, and declaring a work item in one does not refile the other. A cleared chat is never linked to a teammate’s chat, even in a shared dev container folder.
For work you already know, declare the attachment at the start of the session:
This session is for AI-1234. Attach it to that work item.
The kcap-workitems MCP server is installed by CLI setup. It exposes:
| Tool | Use |
|---|---|
declare_work_item | Attach the session and its continuation chain to an issue, PR, or existing item; or create an item by title. |
get_session_work_items | Read the current attachments. |
detach_work_item | Remove an incorrect attachment. |
merge_work_item | Combine duplicate items. |
declare_loose_end | Record a concrete piece of unfinished work. |
Pass exactly one identifier to declare_work_item: issue_key, pr_number, work_item_id, or new_title. Use the issue or PR when one exists. Creating another title-only item for the same ticket makes a duplicate.
issue_key accepts a tracker key (AI-1234), a GitHub issue in the session’s repository (#123), a qualified reference (owner/repo#123), or a GitHub issue URL. A qualified reference must name the session’s own repository or one in the same project.
An explicit declaration takes precedence over automatic correlation and selects the primary item. It does not automatically remove every other attachment. If an attachment is wrong, detach it explicitly.
Declare parts and dependencies
Section titled “Declare parts and dependencies”Ask the agent to record the structure when work spans several items:
AI-1234 breaks into these two tasks. Record them as parts of the parent.
AI-1235 is blocked by AI-1234.
declare_work_breakdown records a parent and its parts. declare_work_relation records blocks or blocked_by. Their matching retract tools remove declarations; get_work_item_topology reads the structure.
Parts and dependencies can cross repositories. They appear in the work item’s Parts and Blocking cards. Declare a dependency only when one item actually must wait for the other.
Correct an attachment
Section titled “Correct an attachment”When the session action menu is available on a work item, choose:
- Reassign to another item… to move the session to the right work item.
- Remove from this item to detach it.
From an agent conversation, use detach_work_item for a wrong attachment, then declare the right one. A parent/parts relationship is not a way to undo an attachment.
Resolve duplicate items
Section titled “Resolve duplicate items”The item’s resolve menu offers Merge into another item… and Mark as standalone. Standalone tells automatic merging to leave this item separate. Allow automatic merging again removes that protection.
If a title-only item later acquires an issue- or PR-keyed counterpart, merge the duplicate into the tracked item. A merged item links to its survivor; eligible actions can undo a merge.
Correct delivery evidence
Section titled “Correct delivery evidence”A PR being mentioned does not always mean it delivered this work. Where the PR action menu is available, Assert delivery PR explicitly identifies it as delivery evidence. Demote delivery assertion removes that assertion.
Use these controls when the inferred state does not match the actual work. Closing a tracker issue and shipping its implementation are separate events.
Visibility
Section titled “Visibility”Access to a work item does not expose private session transcripts. Its session views and retrospective evidence respect session permissions; unavailable sessions may appear as private placeholders.
See Sessions to inspect an attachment, Evals to understand its scores, and Visibility & sharing to change access.