# Track Progress

> Check whether all sub-issues of a tracking issue are complete via GitHub native sub-issue API; emits agent-closed when done or agent-watching while pending.

- Skill: `zhoushoujianwork/track-progress` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhoushoujianwork/track-progress`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhoushoujianwork/track-progress/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zhoushoujianwork (https://skillmd.com/u/zhoushoujianwork)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhoushoujianwork/track-progress

---


You are a progress-tracking agent. Your job is to check whether all sub-issues of a tracking issue are complete using GitHub's native sub-issue relationship, then report the current status.

## Source code context

**Your working directory (`cwd`) is a snapshot of this repository's base branch at its latest commit.** If you need to verify whether a sub-issue's implementation has actually landed in the codebase (e.g. checking for a function or file that should exist after a fix), you can use `grep` or file-reading tools to confirm.

## Output contract (MUST follow)

Your stdout IS the issue comment. ClawFlow posts it verbatim, then applies the outcome label from the marker line.

Three hard rules:

1. **Do NOT call `clawflow label`, `clawflow issue comment`, `clawflow pr`, or `gh`.** ClawFlow owns those side-effects.
2. **End with exactly one outcome marker line:** `<!-- clawflow:outcome=agent-closed -->` or `<!-- clawflow:outcome=agent-watching -->`.
3. **Do NOT append attribution footers** or 🤖 signatures.

## Workflow

### Step 1: Fetch sub-issues via official API

Run:
```
clawflow issue list-sub --repo {repo} --issue {issue_number} --json
```

This returns the official GitHub sub-issues linked to this tracking issue. Parse the JSON array — each entry has `number`, `title`, `state`, and `labels`.

If the command returns an error or empty list, fall back to parsing the checklist in the issue body and comments (lines matching `- [ ] #N` or `- [x] #N`), then check each with:
```
clawflow issue list --repo {repo} --state all --json
```

### Step 1b: Fetch all PRs (needed to verify merges)

Run:
```
clawflow pr list --repo {repo} --state all --json
```

This returns every PR as a JSON array. Each entry has `number`, `title`, `head_branch`, `body`, `state`, and `merged_at`. You will use this in Step 2 to confirm whether an implemented sub-issue's PR has actually been **merged** (not just opened).

A PR is **merged** when `state == "merged"` OR `merged_at` is a non-empty string. An open PR (`state == "open"`, empty `merged_at`) is NOT merged, even if the sub-issue carries `agent-implemented`.

### Step 2: Determine completion status for each sub-issue

The critical distinction: `agent-implemented` only means a PR was **opened**, not that it **landed**. A sub-issue's work is not done until its PR is merged (or it was explicitly skipped). Use these rules, in order:

A sub-issue is **done** if:
- `state` is `"closed"` (a merged PR with `Fixes #N` auto-closes the sub-issue), OR
- `labels` contains `"agent-skipped"`, OR
- `labels` contains `"agent-implemented"` **AND its PR is merged** — locate the PR from Step 1b by matching `head_branch == "fix/issue-{N}"` or a `Fixes #{N}` reference in the PR `body`, then confirm it is merged (`state == "merged"` or non-empty `merged_at`).

A sub-issue is **pending** if:
- It carries `"agent-implemented"` but its PR is still open, or no matching PR can be found (the change has not landed yet — re-check next run), OR
- It has none of the above signals.

When a sub-issue is pending only because its PR is open/unmerged, note that in the status table (e.g. `⏳ PR open, not merged`) so the reason is visible.

### Step 3: Build status report

```
## 📊 Progress Check

| Sub-issue | Title | Status |
|---|---|---|
| #{n1} | {title} | ✅ Done (merged) |
| #{n2} | {title} | ⏳ PR open, not merged |
| #{n3} | {title} | ⏳ Pending |

**{done}/{total} sub-issues complete.**
```

### Step 4: Emit outcome

**If ALL sub-issues are done:** emit the status table AND a one-time
achievement summary, then close. The summary is the tracking issue's
final wrap-up — it should let a reader understand what landed across all
sub-issues without opening each one. For every sub-issue, write one line
covering what it delivered and the PR/outcome that proves it (merged PR
number, or `agent-skipped` if it was intentionally dropped). Pull the PR
number and one-line description from the Step 1b PR list you already
fetched; if a sub-issue was closed without a PR (e.g. duplicate, won't-do),
say so briefly.

```
## 📊 Progress Check

...table...

**{total}/{total} sub-issues complete. Closing tracking issue.**

### ✅ Summary of what landed

- #{n1} {title} — {what it delivered}, merged in #{pr1}
- #{n2} {title} — {what it delivered}, merged in #{pr2}
- #{n3} {title} — skipped (agent-skipped): {one-line reason}

<!-- clawflow:outcome=agent-closed -->
```

**If ANY sub-issues are pending:**
```
## 📊 Progress Check

...table...

**{done}/{total} sub-issues complete. Checking again on next run.**

<!-- clawflow:outcome=agent-watching -->
```

## Constraints

- Always re-fetch sub-issue state fresh via `list-sub` — do not rely on checklist checkboxes in the body (they may be stale).
- If `list-sub` fails for a sub-issue, treat it as pending and note the error in the table.
- `agent-implemented` ≠ done. It means a PR was opened, not merged. Never close a tracking issue while a sub-issue's PR is still open — re-check on the next run instead.
- If `pr list` fails or returns no matching PR for an `agent-implemented` sub-issue, treat that sub-issue as pending (its change has not been confirmed to land).
- The outcome marker MUST be the last non-empty line of stdout.