Task Reconcile

/taskwarrior:task-reconcile

Close the tasks that have gone stale because the GitHub issue or PR they mirror has closed or merged. task-status detects this drift; this skill acts on it, so the queue does not silently fill with trackers for work that already shipped.

A task is "linked" whether it carries a ghid/ghpr UDA or references an issue/PR in its description/annotation text (a #N, an owner/repo#N, or a github.com/owner/repo/(issues|pull)/N URL) — so tasks filed with a plain #N in the description are reconciled too, and a cross-repo owner/repo#N is checked against that repo, not the current one.

When to Use This Skill

Context

• Task CLI available: !task --version
• Git repo detected: !find . -maxdepth 1 -name '.git' -print -quit
• GH auth: !gh auth status

GitHub-mode and project resolution run in the body (Step 1) via the bundled scripts, where stderr suppression and exit-code handling are available — git / gh probes in a Context backtick abort the skill in a no-git/no-remote cwd.

Parameters

Parse $ARGUMENTS:

• --apply — perform the close. Without it the skill runs a dry-run preview first, then asks once before closing.
• --project=<name> — override the auto-detected project filter.
• --all — reconcile across every project (rare; usually you want one repo).
• --limit=N — cap how many linked tasks are inspected (default 200).

Execution

Execute this reconciliation workflow:

Step 1: Resolve scope

Run the shared project resolver (handles --project / --all / git-toplevel / cwd, with no stderr-emitting git probes):

bash "${CLAUDE_SKILL_DIR}/../../scripts/resolve-project.sh" --project-dir "$(pwd)"

Read PROJECT= from the output. GitHub mode must be on (an authenticated gh plus a remote) — the reconcile script reports GH_AVAILABLE=false and exits cleanly if not.

Step 2: Dry-run classification

Run the reconcile script without --apply to classify every linked task:

bash "${CLAUDE_SKILL_DIR}/scripts/reconcile.sh" --project=PROJECT --project-dir "$(pwd)"

It emits one TASK ... line per linked task with its refs count, upstream state(s), a verdict (live / issue-closed / pr-merged / pr-closed), and the close method it would use (bulk / done / keep). A task with several refs is stale only when every ref is done — any open ref keeps it live, any unreadable ref keeps it (uncertain), and a pr-closed among them makes the aggregate pr-closed (kept out of the bounded auto-apply set). Render the stale set as a table for the user, and read the STALE_COUNT / BULK_COUNT / DONE_COUNT summary.

Step 3: Confirm and apply

If STALE_COUNT is 0, report "queue is in sync" and stop.

If --apply was passed in $ARGUMENTS, skip straight to running with --apply. Otherwise confirm once with AskUserQuestion (never a freeform "y/n" — see .claude/rules/skill-execution-structure.md): "Close N stale task(s)?" with options to proceed, review the table again, or cancel.

On confirmation, re-run with --apply:

bash "${CLAUDE_SKILL_DIR}/scripts/reconcile.sh" --apply --project=PROJECT --project-dir "$(pwd)"

Each closed task is annotated with the reason (reconcile: PR #45 merged). Leaf tasks close via a bulk task import round-trip; tasks that block others close via per-task task done so taskwarrior's dependency auto-unblock fires (see REFERENCE.md for why the two paths differ).

Step 4: Report

Print CLOSED_COUNT, the per-task verdicts, and any UNKNOWN_UPSTREAM count (tasks whose issue/PR could not be fetched — left untouched, never closed on uncertainty). Suggest /taskwarrior:task-status to confirm the queue is clean.

Agentic Optimizations

Quick Reference

Related

• /taskwarrior:task-status — detects the drift this skill resolves
• /taskwarrior:task-done — close one task with a landing commit
• /taskwarrior:task-add — file the linked tasks this skill later reconciles
• .claude/rules/gh-json-fields.md — state/mergedAt (never a merged field)
• .claude/rules/parallel-safe-queries.md — the export | jq idiom
• taskwarrior-plugin/skills/task-reconcile/REFERENCE.md — bulk-vs-done routing, task import caveats