| name | sync-tracker |
| description | Reconcile merged PRs and completed work against open tracker items. Mode-aware: works in local, tracker, and both modes. Supports --dry-run and --import-backup [file]. Usage: /sync-tracker [--dry-run] [--import-backup [file]] |
| argument-hint | --dry-run | --import-backup [file] |
Core Philosophy: Tracker items that have been delivered (PR merged) should be closed, and work that was deferred should be open — reconciliation runs in both directions. This skill is the interactive judgment layer the sweep hook (hooks/tracker-sync.js) points at — the sweep handles explicit evidence mechanically; this skill handles ambiguous evidence with user confirmation, and harvests deferrals that were only ever written as prose (Step 6.5, per rules/deferrals.md).
Triggers: "sync tracker", "close completed issues", "update tracker", "reconcile PRs", "clean up tracker", "import backup", "what did we defer", "find deferred work"
You are the tracker synchronization agent. Your job is to find tracker items that have been delivered but are still open, and close them. You are mode-aware: behavior adapts to local, tracker, or both mode.
Parse $ARGUMENTS:
--dry-run → report what would be closed, but don't actually close anything.--import-backup [file] → import mode (D23): convert unchecked items from a backup file into tracker tasks. Default source: tasks/todo-manual-backup.md. Also accepts tasks/plan.md as a source (D29).
Step 1 — Detect mode
Read .claude/.harness-manifest.json:
tracker field → the active tracker type (github, todoist, ado, local).trackerMirror field → whether mirror mode is active.- Derive the mode:
tracker === 'local' → local mode- External tracker +
trackerMirror === true → both mode
- External tracker + no mirror → tracker mode
If no manifest or no tracker configured, fall back to tasks/tracker-config.md **Type:** field or adapter script detection in .claude/trackers/active/.
Note the mode for subsequent steps.
Step 2 — Route by argument
If --import-backup was passed, jump to Step 7 (Import backup).
Otherwise, continue to Step 3.
Step 3 — Find delivered items
Gather evidence of completed work. todo.md is NEVER an evidence source — it is a generated dashboard (D9). Evidence comes from PRs and sprint tables only.
Source A — Merged PRs:
gh pr list --state merged --limit 50 --json number,title,body,mergedAt
Extract references based on mode:
- Local mode: look for anchored
Task: <N> trailer lines in PR bodies (one per line, ^Task: \d+$). Never match prose like "builds on task 42".
- Tracker/both mode: look for GitHub closing keywords (
Closes #123, Fixes #123, Resolves #123) and ADO references (Fixes AB#204). Also check PR titles.
Skip gracefully if gh is not available or not authenticated.
Source B — Sprint files (ambiguous — flag only):
Glob tasks/sprint*.md and read the latest. Find rows in the Master Status Table where the Status column shows "Done" but no merged PR is referenced. These are ambiguous — flag them for manual review but do NOT auto-close (D20).
Collect all unique tracker IDs that appear to be delivered.
Step 4 — Check tracker state
For each candidate ID, call the active tracker adapter to check current state:
bash .claude/trackers/active/get-issue.sh <ID>
Parse the output to determine if the item is already closed/completed. Filter down to only items that are still open.
Step 5 — Report
Show a summary table:
| ID | Title | Evidence | Current State | Action |
|---|
| #123 | Fix login bug | PR #45 merged (Closes #123) | Open | Close |
| #456 | Add dark mode | Sprint table "Done" (no PR) | Open | ⚠ Ambiguous — needs confirmation |
| #789 | Refactor auth | PR #67 merged | Already closed | Skip |
If --dry-run was passed, report:
Dry run complete. [N] items have explicit delivery evidence and would be closed. [M] items have ambiguous evidence and need manual confirmation. Run /sync-tracker (without --dry-run) to close them.
…then skip Step 6 and continue to Step 6.5 (which is also read-only under --dry-run).
Step 6 — Close delivered items
Explicit evidence items: close without asking:
bash .claude/trackers/active/close-issue.sh <ID> "Delivered in PR #<N>"
Ambiguous evidence items: ask the user for confirmation on each one before closing.
Report each closure result.
Both mode — regenerate mirror: after closing items, regenerate tasks/todo.md:
bash .claude/trackers/lib/render-todo.sh tasks/issues
Output:
Sync complete. Closed [N] delivered items in [tracker type]. [M] items were already closed. [K] open items have no delivery evidence (still in progress).
Then continue to Step 6.5 — closing delivered work is only half of reconciliation; the other half
is work that was deferred and never registered.
Step 6.5 — Harvest orphaned deferrals
Per rules/deferrals.md, a deferral is only real if it is a tracker item — prose in a PR body or a
notes file never resurfaces on its own. This step finds deferrals recorded before that rule, or by a
run that skipped it.
Scan these sinks for deferral language (Deferred, Follow-up, follow-ups, TODO later,
known gap, not required by, tracked as a follow-up):
grep -rin "deferred\|follow-up\|known gap" tasks/notes.md tasks/lessons.md tasks/stories/*/decisions-log.md tasks/stories/*/evaluation.md 2>/dev/null
gh pr list --state merged --limit 50 --json number,body --jq '.[] | select(.body | test("(?i)deferred|follow-up")) | "PR #\(.number)"'
Drop any line that already carries a tracker id (#123, an ADO AB#204, or a Todoist task id) —
that one is registered and will surface on its own.
Report the survivors as a table — source, the line, and what it appears to cost:
| Source | Deferred item | Cost while undone | Ship test |
|---|
| notes.md ledger (PR #22) | Model→window map hardcoded | Recycles context early on the configured model | ⚠ needs answer |
Apply the ship test to each survivor before offering it as a task (rules/deferrals.md): with this
left undone, does the shipped change behave incorrectly for the project's real configured inputs?
A survivor that fails the test is not backlog — it is an unshipped bug in already-merged code.
Flag it as such, loudly and separately from the backlog list. A sweep is exactly where a mislabeled
blocker would otherwise get laundered into a low-priority task.
Never register silently. Ask the user which survivors to create, then for each approved one:
bash .claude/trackers/active/create-issue.sh "<title>" "<what's undone / cost / ship-test answer / source PR>" "deferred"
If --dry-run was passed, report the table and stop — create nothing.
Step 7 — Import backup (--import-backup)
This flow serves the mode migration (D23) and mode switches (D25).
7a. Determine source file:
- If a file path was given after
--import-backup, use that.
- Default:
tasks/todo-manual-backup.md.
- Also accept
tasks/plan.md (D29: retired solo plan).
Read the source file. If it doesn't exist, stop with a clear message.
7b. Parse the file for unchecked items. Look for markdown list items that are NOT checked:
- [ ] ... or - ... (plain bullets) → candidate items- [x] ... or - [X] ... → skip (already done)
Extract a title for each candidate item.
7c. Cross-check each candidate against open items in the active backend:
bash .claude/trackers/active/list-issues.sh
Flag items that look like duplicates of existing open items.
7d. Present the full list to the user. For each candidate, show:
- The original text from the backup
- Whether it looks like a duplicate
- Ask: Create this as a new task? (yes/skip)
7e. For each approved item, create it:
bash .claude/trackers/active/create-issue.sh "<title>" "<body>" ""
7f. Summary:
Import complete. Created [N] tasks from [source file]. [M] items skipped. The source file has NOT been deleted — review it and delete manually when satisfied.
Never delete the source file — tell the user to do it when done.
Error handling
- If
close-issue.sh or create-issue.sh fails for an item, log the error and continue with the remaining items. Report failures at the end.
- If the tracker adapter is not installed, stop with a clear message: "No tracker adapter found. Run the installer to configure a tracker."
- If no delivered items are found, say so and exit cleanly.
- If
gh is not available, skip PR evidence gathering and note it in the report.
