# Kata Track Progress
> Check project progress, show context, and route to next action (execute or plan). Triggers include "progress".
- Skill: `gannonh/kata-track-progress` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add gannonh/kata-track-progress`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gannonh/kata-track-progress/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gannonh (https://skillmd.com/u/gannonh)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gannonh/kata-track-progress
---
Check project progress, summarize recent work and what's ahead, then intelligently route to the next action - either executing an existing plan or creating the next one.
Provides situational awareness before continuing work.
**Verify planning structure exists:**
Use Bash (not Glob) to check—Glob respects .gitignore but .planning/ is often gitignored:
```bash
test -d .planning && echo "exists" || echo "missing"
```
If no `.planning/` directory:
```
No planning structure found.
Run /kata-new-project to start a new project.
```
Exit.
If missing STATE.md: suggest `/kata-new-project`.
**If ROADMAP.md missing but PROJECT.md exists:**
This means a milestone was completed and archived. Go to **Route F** (between milestones).
If missing both ROADMAP.md and PROJECT.md: suggest `/kata-new-project`.
**Pre-flight: Check roadmap format (auto-migration)**
If ROADMAP.md exists, check format and auto-migrate if old:
```bash
if [ -f .planning/ROADMAP.md ]; then
node "${CLAUDE_PLUGIN_ROOT}/skills/kata-track-progress/scripts/kata-lib.cjs" check-roadmap 2>/dev/null
FORMAT_EXIT=$?
if [ $FORMAT_EXIT -eq 1 ]; then
echo "Old roadmap format detected. Running auto-migration..."
fi
fi
```
**If exit code 1 (old format):**
Invoke kata-doctor in auto mode:
```
Skill("kata-doctor", "--auto")
```
Continue after migration completes.
**If exit code 0 or 2:** Continue silently.
**Load full project context:**
- Read `.planning/STATE.md` for living memory (position, decisions, issues)
- Read `.planning/ROADMAP.md` for phase structure and objectives
- Read `.planning/PROJECT.md` for current state (What This Is, Core Value, Requirements)
- Read `.planning/config.json` for settings (model_profile, workflow toggles)
**Load PR workflow config:**
```bash
PR_WORKFLOW=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-track-progress/scripts/kata-lib.cjs" read-config "pr_workflow" "false")
```
**Gather recent work context:**
- Find the 2-3 most recent SUMMARY.md files
- Extract from each: what was accomplished, key decisions, any issues logged
- This shows "what we've been working on"
**Parse current position:**
- From STATE.md: current phase, plan number, status
- Calculate: total plans, completed plans, remaining plans
- Note any blockers or concerns
- Check for CONTEXT.md: For phases without PLAN.md files, check if `{phase}-CONTEXT.md` exists in phase directory
- Count pending issues: `find .planning/issues/open -maxdepth 1 -name "*.md" 2>/dev/null | wc -l`
- Check for active debug sessions: `find .planning/debug -maxdepth 1 -name "*.md" 2>/dev/null | grep -v resolved | wc -l`
**Present rich status report:**
````
# [Project Name]
**Progress:** [████████░░] 8/10 plans complete
**Profile:** [quality/balanced/budget]
## Recent Work
- [Phase X, Plan Y]: [what was accomplished - 1 line]
- [Phase X, Plan Z]: [what was accomplished - 1 line]
## Current Position
Phase [N] of [total]: [phase-name]
Plan [M] of [phase-total]: [status]
CONTEXT: [✓ if CONTEXT.md exists | - if not]
## Key Decisions Made
- [decision 1 from STATE.md]
- [decision 2]
## Blockers/Concerns
- [any blockers or concerns from STATE.md]
## Pending Issues
- [count] pending — /kata-check-issues to review
## Active Debug Sessions
- [count] active — /kata-debug to continue
(Only show this section if count > 0)
## PR Status
(Only show this section if PR_WORKFLOW is true)
Check for PR on current branch:
```bash
if [ "$PR_WORKFLOW" = "true" ]; then
CURRENT_BRANCH=$(git branch --show-current)
PR_INFO=$(gh pr list --head "$CURRENT_BRANCH" --json number,state,title,url --jq '.[0]' 2>/dev/null)
if [ -n "$PR_INFO" ] && [ "$PR_INFO" != "null" ]; then
PR_NUMBER=$(echo "$PR_INFO" | jq -r '.number')
PR_STATE=$(echo "$PR_INFO" | jq -r '.state')
PR_TITLE=$(echo "$PR_INFO" | jq -r '.title')
PR_URL=$(echo "$PR_INFO" | jq -r '.url')
# Check if draft
if [ "$PR_STATE" = "OPEN" ]; then
IS_DRAFT=$(gh pr view "$PR_NUMBER" --json isDraft --jq '.isDraft' 2>/dev/null)
if [ "$IS_DRAFT" = "true" ]; then
STATE_DISPLAY="Draft"
else
STATE_DISPLAY="Ready for review"
fi
elif [ "$PR_STATE" = "MERGED" ]; then
STATE_DISPLAY="Merged"
elif [ "$PR_STATE" = "CLOSED" ]; then
STATE_DISPLAY="Closed"
else
STATE_DISPLAY="$PR_STATE"
fi
fi
fi
````
**If PR exists:**
```
## PR Status
PR #[number]: [title]
Status: [Draft | Ready for review | Merged]
URL: [url]
```
**If no PR exists:**
```
## PR Status
No open PR for current branch.
Branch: [current_branch]
```
## What's Next
[Next phase/plan objective from ROADMAP]
````
**Determine next action based on verified counts.**
**Step 1: Find current phase directory and count plans, summaries, and issues**
Find the current phase directory using universal discovery:
```bash
PADDED=$(printf "%02d" "$CURRENT_PHASE" 2>/dev/null || echo "$CURRENT_PHASE")
PHASE_DIR=""
for state in active pending completed; do
PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | head -1)
[ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${CURRENT_PHASE}-*" 2>/dev/null | head -1)
[ -n "$PHASE_DIR" ] && break
done
# Fallback: flat directory (backward compatibility)
if [ -z "$PHASE_DIR" ]; then
PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | head -1)
[ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${CURRENT_PHASE}-*" 2>/dev/null | head -1)
fi
````
List files in the current phase directory:
```bash
find "${PHASE_DIR}" -maxdepth 1 -name "*-PLAN.md" 2>/dev/null | wc -l
find "${PHASE_DIR}" -maxdepth 1 -name "*-SUMMARY.md" 2>/dev/null | wc -l
find "${PHASE_DIR}" -maxdepth 1 -name "*-UAT.md" 2>/dev/null | wc -l
```
State: "This phase has {X} plans, {Y} summaries."
**Step 1.5: Check for unaddressed UAT gaps**
Check for UAT.md files with status "diagnosed" (has gaps needing fixes).
```bash
# Check for diagnosed UAT with gaps
find "${PHASE_DIR}" -maxdepth 1 -name "*-UAT.md" -exec grep -l "status: diagnosed" {} + 2>/dev/null
```
Track:
- `uat_with_gaps`: UAT.md files with status "diagnosed" (gaps need fixing)
**Step 2: Route based on counts**
| Condition | Meaning | Action |
| ------------------------------- | ----------------------- | ----------------- |
| uat_with_gaps > 0 | UAT gaps need fix plans | Go to **Route E** |
| summaries < plans | Unexecuted plans exist | Go to **Route A** |
| summaries = plans AND plans > 0 | Phase complete | Go to Step 3 |
| plans = 0 | Phase not yet planned | Go to **Route B** |
---
**Route A: Unexecuted plan exists**
Find the first PLAN.md without matching SUMMARY.md.
Read its `` section.
```
---
## ▶ Next Up
**{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]
{If PR_WORKFLOW is true AND PR exists: PR #[number] ([state]) — [url]}
`/kata-execute-phase {phase}`
`/clear` first → fresh context window
---
```
---
**Route B: Phase needs planning**
Check if `{phase}-CONTEXT.md` exists in phase directory.
**If CONTEXT.md exists:**
```
---
## ▶ Next Up
**Phase {N}: {Name}** — {Goal from ROADMAP.md}
✓ Context gathered, ready to plan
`/kata-plan-phase {phase-number}`
`/clear` first → fresh context window
---
```
**If CONTEXT.md does NOT exist:**
```
---
## ▶ Next Up
**Phase {N}: {Name}** — {Goal from ROADMAP.md}
`/kata-plan-phase {phase}` — plan next phase
`/clear` first → fresh context window
---
**Also available:**
- `/kata-discuss-phase {phase}` — gather context and clarify approach
- `/kata-listing-phase-assumptions {phase}` — see Claude's assumptions
---
```
---
**Route E: UAT gaps need fix plans**
UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.
```
---
## ⚠ UAT Gaps Found
**{phase}-UAT.md** has {N} gaps requiring fixes.
`/kata-plan-phase {phase} --gaps`
`/clear` first → fresh context window
---
**Also available:**
- `/kata-execute-phase {phase}` — execute phase plans
- `/kata-verify-work {phase}` — run more UAT testing
---
```
---
**Step 3: Check milestone status (only when phase complete)**
Read ROADMAP.md and identify:
1. Current phase number
2. All phase numbers in the current milestone section
Count total phases and identify the highest phase number.
State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
**Route based on milestone status:**
| Condition | Meaning | Action |
| ----------------------------- | ------------------ | ----------------- |
| current phase < highest phase | More phases remain | Go to **Route C** |
| current phase = highest phase | Milestone complete | Go to **Route D** |
---
**Route C: Phase complete, more phases remain**
Read ROADMAP.md to get the next phase's name and goal.
```
---
## ✓ Phase {Z} Complete
## ▶ Next Up
{If PR_WORKFLOW is true AND PR exists:
**⚠️ Merge PR #[number] first** — [url]
Then continue with:
}
**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
`/kata-plan-phase {Z+1}` — plan next phase
`/clear` first → fresh context window
---
**Also available:**
- `/kata-discuss-phase {Z+1}` — gather context and clarify approach
- `/kata-verify-work {Z}` — user acceptance test before continuing
---
```
---
**Route D: Milestone complete**
```
---
## 🎉 Milestone Complete
All {N} phases finished!
## ▶ Next Up
{If PR_WORKFLOW is true: **⚠️ Merge all phase PRs first** before completing milestone
Then continue with:
}
**Complete Milestone** — archive and prepare for next
`/kata-complete-milestone`
`/clear` first → fresh context window
---
**Also available:**
- `/kata-verify-work` — user acceptance test before completing milestone
---
```
---
**Route F: Between milestones (ROADMAP.md missing, PROJECT.md exists)**
A milestone was completed and archived. Ready to start the next milestone cycle.
Read MILESTONES.md to find the last completed milestone version.
---
## ✓ Milestone v{X.Y} Complete
Ready to plan the next milestone.
## ▶ Next Up
**Start Next Milestone** — questioning → research → requirements → roadmap
`/kata-add-milestone`
`/clear` first → fresh context window
---
**Handle edge cases:**
- Phase complete but next phase not planned → offer `/kata-plan-phase [next]`
- All work complete → offer milestone completion
- Blockers present → highlight before offering to continue
- Handoff file exists → mention it, offer `/kata-resume-work`
- [ ] Rich context provided (recent work, decisions, issues)
- [ ] Current position clear with visual progress
- [ ] What's next clearly explained
- [ ] Smart routing: /kata-execute-phase if plans exist, /kata-plan-phase if not
- [ ] User confirms before any action
- [ ] Seamless handoff to appropriate kata command