kata-track-progress

What this skill does

<objective>
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.
</objective>

<process>

<step name="verify">
**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`.
</step>

<step name="preflight_roadmap_format">
**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.
</step>

<step name="load">
**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")
```

  </step>

<step name="recent">
**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"
  </step>

<step name="position">
**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`
  </step>

<step name="report">
**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]

````

</step>

<step name="route">
**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 `<objective>` 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}`

<sub>`/clear` first → fresh context window</sub>

---
```

---

**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}
<sub>✓ Context gathered, ready to plan</sub>

`/kata-plan-phase {phase-number}`

<sub>`/clear` first → fresh context window</sub>

---
```

**If CONTEXT.md does NOT exist:**

```
---

## ▶ Next Up

**Phase {N}: {Name}** — {Goal from ROADMAP.md}

`/kata-plan-phase {phase}` — plan next phase

<sub>`/clear` first → fresh context window</sub>

---

**Also available:**
- `/kata-discuss-phase {phase}` — ga