Work Tracking

Work tracking is a lightweight system for capturing improvements, bugs, tasks, goals, deferred suggestions, and technical debt as structured markdown entries. Items live in a work/ directory at the repository root, flow through a record-pluck-accept lifecycle, and stay scoped to the project they belong to.

Enabling work tracking

Toggle work tracking on at Settings > r26D > Work Tracking. When enabled, the sidebar gains context menu items for recording, plucking, and accepting work items on any repository that has a work/ directory.

The manual /xp_work slash command works regardless of whether the toggle is on or off. The toggle only controls the GUI launcher surfaces: sidebar context menu entries and modal dialogs.

The work/ directory

Eight canonical files live under work/ at the repo root. Each file tracks a specific category and uses a unique ID prefix. Every entry gets a stable identifier (e.g. IMP-7, BUG-3) that never changes after assignment.

File	Prefix	Purpose
IMPROVEMENTS.md	IMP	Product and workflow improvement ideas
BUGS.md	BUG	Defects and incorrect behavior
TODO.md	TODO	Planned tasks and features
USER_GOALS.md	GOAL	User outcomes and scenarios
DEFERRED.md	DEF	Valid suggestions parked for later
TECH_DEBT.md	DEBT	Known shortcuts and cleanup tasks
ITERATION.md	ITER	Active work for the current iteration
ACCEPTANCE.md	ACC	Work waiting for human verification

Each file carries a **Last id:** PREFIX-N counter in its header. The counter is monotonically non-decreasing: it increments when new entries are added but never decreases when entries are removed, moved, or plucked.

Entry format

Every entry follows the same structure:

## Entry title

**Id:** IMP-42

**Date:** 2026-05-28

**Why:** Users need feedback on whether the push succeeded or failed.

**Issue:** When a user clicks to push, there is no visual confirmation.

**Suggestion:** Display a toast notification on push completion.

The Why field captures rationale for the item. Issue describes the problem. Suggestion is an optional implementation direction. Bug entries use Expected Behavior instead of Suggestion.

Recording items

From the sidebar

Right-click a repository in the sidebar and choose one of the recording actions:

• Record Improvement — appends to IMPROVEMENTS.md
• Record Bug — appends to BUGS.md
• Record Todo — appends to TODO.md
• Defer Suggestion — appends to DEFERRED.md
• Record Tech Debt — appends to TECH_DEBT.md
• Record Goal — appends to USER_GOALS.md

Each action opens the record modal with three fields:

Field	Required	Notes
Description	Yes	What needs to change or what went wrong
Label	No	Project area chips; only shown when work/labels.toml exists. See Labels below
Why does this matter?	No	Rationale for prioritization; persisted as **Why:** in the entry
Suggestion	No	Implementation direction; shown only for improvements and deferred items

The item is assigned the next available ID, committed, and confirmed via a toast notification.

Labels

When a repository contains a work/labels.toml file, the record modal shows a row of label chips between Description and Why. Each [labels.<name>] table in the registry becomes a selectable chip. A special repo chip is always available and represents repository-level work.

Selecting repo clears project labels; selecting any project label clears repo. Multiple project labels can be combined. The selection is remembered per repository and restored the next time the modal opens — stale labels that no longer appear in the registry are silently dropped.

When labels are selected, the backend sends a hint to the xp_work skill so the recorded entry carries the chosen label. When no labels are selected, the skill infers the label from the item’s content and working directory.

Drafts

When a recording attempt fails (spawn error, non-zero exit, or validation failure), a draft is saved to work/.drafts/<timestamp>_<type>.md. The draft preserves the description, why, suggestion, and — when applicable — a **Label:** line and an **Error:** line describing the failure.

From chat

Type a prefix at the start of a chat message to record an item without opening the modal:

Prefix	Target file
improve: or feedback:	IMPROVEMENTS.md
bug: or bug report:	BUGS.md
feat:, todo:, or task:	TODO.md
goal:, scenario:, or user_goal:	USER_GOALS.md
deferred: or defer:	DEFERRED.md
tech debt: or debt:	TECH_DEBT.md

For example, typing bug: Toast z-index covers sidebar file list in the chat composer records a new bug entry.

Pluck workflow

Plucking takes a queued item through planning, implementation, verification, and cleanup in one streamlined flow.

From the sidebar

Right-click a repository and select Pluck Work Item. The pluck modal loads all queued items from the six source files (IMPROVEMENTS.md, TODO.md, USER_GOALS.md, BUGS.md, DEFERRED.md, TECH_DEBT.md), grouped by category. Click an item to expand its description, then click Pluck into Workspace to begin.

A search box at the top of the modal narrows items by id or title — type any substring and only matching items remain visible. When items carry more than one distinct project label (from the **Label:** field in the work file, defaulting to repo), a project selector appears next to the search box. Selecting a project keeps only items whose labels include it. Both filters combine: items must match the search text and the selected project. The search text and project selection are remembered per repository for the rest of the session, so opening the modal on another repository never applies a filter chosen elsewhere; a remembered project that none of the repository’s items carry falls back to All projects.

Plucking creates a new workspace named after the item (e.g. imp-42-show-toast-for-push), switches to it, and sends /xp_work pluck IMP-42 to the chat agent. The agent then:

1. Marks the item as In progress in the source file
2. Plans the implementation (agent prompts you to choose a planning mode)
3. Implements the change
4. Verifies the result
5. Squash-merges when complete
6. Removes the item from the source file
7. Optionally creates an ACC-N entry in ACCEPTANCE.md if human verification is needed
8. Commits with the original item body in the commit message and adds a line to CHANGELOG.md

In-progress items

Items already being worked on in another workspace appear in a trailing In Progress section at the bottom of the pluck modal with a badge and dimmed styling. Re-plucking an in-progress item requires explicit confirmation.

From chat

Type pluck: <reference> in chat and reference the item by title or ID to start the pluck workflow without opening the modal.

Iteration management

Items can also flow through a more traditional iteration model using chat commands:

Command	Effect
add to iteration: <reference>	Moves an item from a queue file to ITERATION.md
done: <reference>	Marks an iteration item as complete
needs acceptance: <reference>	Moves an iteration item to ACCEPTANCE.md

When an item moves between files, it gets a new ID in the target file (e.g. IMP-7 becomes ITER-5) and a **Source id:** field preserving traceability.

Acceptance

Items that need human verification land in ACCEPTANCE.md. Each acceptance entry includes:

• Description of what was built
• Source and Source id linking back to the original item
• Acceptance Criteria as a checklist
• Pre-verification steps (e.g. merge a branch before testing)

Accepting from the sidebar

Right-click a repository and select Accept Work Item. The accept modal lists all pending acceptance items. Expand an item to see its criteria and context, then click Investigate in Workspace to create a dedicated workspace for verification.

The acceptance workspace opens with the agent briefed on the criteria but explicitly instructed to wait for human verification. When you confirm the criteria are met, the agent runs /xp_work accept ACC-N to remove the entry and commit.

Accepting from chat

Type accept: <reference> to accept a verified item directly.

Detection

Workbench detects work tracking support by checking whether the repository has a work/ directory. When the toggle is enabled, each repository is probed on startup and when the setting changes. Repositories without a work/ directory do not show work tracking context menu items.

See also

• r26D Company Settings — the settings section where work tracking lives
• Slash Commands — for /xp_work command usage
• Settings — full settings reference