taskgraph-inspect-work

name	taskgraph-inspect-work
description	Inspect Taskgraph items, hierarchy, dependencies, readiness, blockers, context, and change history through the Taskgraph tools. Use when an agent needs to find work, understand status, diagnose why work is blocked, review recent changes, or prepare execution context.

Taskgraph Inspect Work

Use read tools first to build a bounded view of Taskgraph state. Resolve references, inspect the item, then widen to context, graph, blockers, or changes only as needed.

Choose the smallest read

• tg_resolve: turn an ID, canonical path, or alias into one item. Stop on AMBIGUOUS_REFERENCE or NOT_FOUND.
• tg_get_item: get one item plus bounded ancestors, children, and dependencies as returned by Taskgraph.
• tg_search_items: find items by a text query. Set limit no higher than needed; the server caps it at 200.
• tg_get_graph: inspect hierarchy and the direct dependency neighborhood. Set max_items; the server caps it at 500.
• tg_context_bundle: prepare deterministic context for one item. Pass ref directly, or use source: {"item": ...}.
• tg_explain_blocked: return readiness reasons for one item.
• tg_list_changes: inspect audit changes after a known revision with after_revision and a bounded limit.

Do not request a whole workspace when a path, project, or item is enough. Preserve IDs, canonical paths, versions, and revisions in your notes.

Inspect an item

1. Resolve the user reference.
2. Call tg_get_item with the stable ID or canonical path.
3. If the item is part of a plan, call tg_get_graph with a small max_items to see ancestors, children, and nearby relationships.
4. If an agent will act on it, call tg_context_bundle and keep within the requested context budget when the server supports one.
5. When inspecting a plan, note actions that read like phases — broad titles, missing acceptance criteria, or several unrelated deliverables under one action — and report them to the caller for decomposition. Do not patch them during an inspection.

The current implementation returns item data with fields such as status, effective_state, execution_mode, child_gate, completion_policy, priority, version, last_revision, and canonical path. Use those fields to explain what the system knows; do not infer missing fields.

Explain readiness or blockage

Call tg_explain_blocked for the item. Read every returned reason. Common codes include:

• NOT_EXECUTABLE: the item is a container, not an action.
• STATUS_NOT_OPEN: the stored status is not open.
• ARCHIVED or ARCHIVED_ANCESTOR: the item is hidden from normal work.
• ANCESTOR_STATUS: a parent gate is closed.
• NOT_BEFORE: the start time has not passed.
• ACTIVE_CLAIM: another active claim exists.
• ASSIGNED_TO_OTHER: the item belongs to another actor.
• MISSING_CAPABILITY: the current agent session lacks a required capability.
• AGENT_CLAIM_LIMIT: the session already holds its claim limit.
• INCOMPLETE_CHILDREN: a child gate is not satisfied.
• UNSATISFIED_DEPENDENCY: a hard blocker is not done or skipped.
• MANUAL_BLOCKER: a manual blocker remains unresolved.

For a dependency issue, inspect the BlockingItem or the nearby graph. Explain the direction as “A blocks B” so the action is clear: finish or skip A, waive or remove the relationship only with user authority, or change the plan.

Inspect recent changes

Use tg_list_changes only when the caller has a revision or wants a recent audit view. Start with a small limit. Use the returned revision range to avoid rereading the same changes.

Compare the change record with a fresh tg_get_item before claiming that a field changed. A revision is workspace-wide; an item version controls safe item patches.

Keep inspection read-only

• Do not patch, create, claim, release, waive, or report work during an inspection unless the user asks for that change.
• Do not expose claim tokens or treat them as ordinary item data.
• If a read fails, show the Taskgraph error code and the next safe read to try. Do not replace a missing result with a guess.
• Keep graph and search results bounded. State when the returned result is truncated or limited.
• The pi extension publishes full schemas for every tool, including tg_list_changes. If a strict client rejects valid arguments, report the error and stop.