/batch-complete

name: batch-complete
description: "Completes or cancels multiple items at once — closes out features, cleans up old work, and archives completed workstreams. Use when a user says: close out this feature, complete everything under X, cancel this workstream, clean up old items, bulk complete, finish this feature, or archive completed work."
argument-hint: "[optional: root item UUID or title to complete]"

batch-complete — Bulk Complete or Cancel Items

Close out a feature subtree, cancel an abandoned workstream, or clean up stale items in one operation. Handles gate checks, active-item warnings, and reports exactly what succeeded and what was skipped.

---

Step 1 — Identify Scope

Resolve `$ARGUMENTS` to a UUID via `query_items` search (`operation="search"`, `query=$ARGUMENTS`, `limit=5`); if ambiguous, present matches via `AskUserQuestion`.

**If `$ARGUMENTS` is empty**, classify the request from conversation context:

• **Feature subtree**: user mentions completing "everything under" a named item → search for that item, use `rootId`
• **Specific items**: user lists names or IDs → collect each UUID, use `itemIds`
• **Cleanup**: user wants to clear old/stale items → search by status or title fragment, collect UUIDs, use `itemIds`

If scope still cannot be determined, ask via `AskUserQuestion`: "Which item (or items) do you want to complete? Provide a root UUID, a title fragment, or a list of item IDs."

---

Step 2 — Preview Impact

Before executing, show the user what will happen. Call:

query_items(operation="overview", itemId="<rootId>")

Parse the child counts by role and present a preview table. Use the trigger chosen (or likely to be chosen) to set the action label — `trigger="complete"` shows "will be completed"; `trigger="cancel"` shows "will be cancelled":

◆ Impact Preview — "Auth System Feature"  [trigger: complete]
  ○ queue:    3 items (will be completed)
  ◉ work:     1 item  (active — will be force-completed)
  ◉ review:   1 item  (active — will be force-completed)
  ✓ terminal: 2 items (already done — will be skipped)

◆ Impact Preview — "Auth System Feature"  [trigger: cancel]
  ○ queue:    3 items (will be cancelled)
  ◉ work:     1 item  (active — will be force-cancelled)
  ◉ review:   1 item  (active — will be force-cancelled)
  ✓ terminal: 2 items (already done — will be skipped)

**For `itemIds` path** (no root item): call `query_items(operation="get", itemId="<uuid>")` on each item and build the same role-grouped preview table from the individual results. For large lists (10+ items), use `query_items(operation="search")` with filters instead of individual get calls.

**If any items are in `work` or `review`**, warn the user that active work will be force-completed (gate checks still apply). Use `AskUserQuestion` with three options:

◆ 2 items are currently active (work or review).
  How would you like to proceed?
  1. Proceed — complete everything including active items
  2. Cancel active items instead — use trigger="cancel" (bypasses gates)
  3. Abort — leave everything as-is

Wait for the user's choice before continuing. Record whether to use `trigger="complete"` or `trigger="cancel"`.

---

Step 3 — Gate Check

**Skip this step if `trigger="cancel"` was already chosen in Step 2** — cancel bypasses all gates, so gate checking is unnecessary.

For `trigger="complete"`, gate previewing is best-effort. `complete_tree` performs the definitive gate check during execution and reports any failures in its response. A lightweight pre-check is still useful to surface issues before committing — call `get_context` on each child from Step 2's results rather than on the root item (the root itself is not completed by `complete_tree`, only its descendants are):

get_context(itemId="<child-uuid>")   ← repeat for each child listed in Step 2

If any child's gate status shows missing required notes, display them:

⊘ Gate Warnings (preview — definitive check runs at execution):
  "Implement login" — missing: implementation-notes (work, required)
  "Write tests" — missing: session-tracking (work, required)

Then offer three options via `AskUserQuestion`:

◆ Some items have unfilled required notes and will be skipped by the gate.
  What would you like to do?
  1. Fill notes first — use manage_notes(operation="upsert") to fill each item's required notes, then return here
  2. Use cancel trigger — bypasses all gates, marks items as "cancelled"
  3. Proceed anyway — gated items will be skipped, others will complete

Call `get_context(itemId=...)` to retrieve `guidanceKey` for items with missing notes, then resolve its text via `query_items(operation="schema", itemId=...)`. Use the guidance as authoring instructions before filling.

Wait for the user's choice. If they choose option 2, switch to `trigger="cancel"` for the execution step.

If `complete_tree` reports gate failures in Step 4, fill the missing notes and rerun `complete_tree` — items already in terminal are silently skipped on subsequent runs.

---

Step 4 — Execute

Call `complete_tree` with the chosen trigger:

**Feature subtree (rootId):**

complete_tree(rootId="<uuid>", trigger="complete")

**Specific items (itemIds):**

complete_tree(itemIds=["<uuid-1>", "<uuid-2>", "<uuid-3>"], trigger="complete")

**Cancel variant (bypasses gates):**

complete_tree(rootId="<uuid>", trigger="cancel")

Parse the response and present results:

✓ Batch Complete — "Auth System Feature"
  ✓ Design API schema — completed
  ✓ Set up database — completed
  ⊘ Implement login — skipped (gate: missing implementation-notes)
  ✓ Write unit tests — completed
  — Integration tests — skipped (dependency on "Implement login")

  Summary: 3/5 completed | 1 gate failure | 1 dependency skip

Use these symbols:

• `✓` — applied: true (completed or cancelled)
• `⊘` — gate failure (gateErrors present)
• `—` — skipped due to dependency on a failed item

---

#