kata-check-issues

What this skill does

<objective>
List all open issues, allow selection, load full context for the selected issue, and route to appropriate action.

Enables reviewing captured ideas and deciding what to work on next.
</objective>

<context>
@.planning/STATE.md
@.planning/ROADMAP.md
</context>

<process>

<step name="deprecation_notice">
**If the user invoked with "todo" vocabulary** (e.g., "check todos", "list todos", "pending todos"):

Display:

> **Note:** "todos" is now "issues". Using `/kata-check-issues`.

Then proceed with the action (non-blocking).
</step>

<step name="check_and_migrate">
Check if legacy `.planning/todos/` exists and needs migration:

```bash
if [ -d ".planning/todos/pending" ] && [ ! -d ".planning/todos/_archived" ]; then
  # Create new structure
  mkdir -p .planning/issues/open .planning/issues/in-progress .planning/issues/closed

  # Copy pending todos to open issues
  cp .planning/todos/pending/*.md .planning/issues/open/ 2>/dev/null || true

  # Copy done todos to closed issues
  cp .planning/todos/done/*.md .planning/issues/closed/ 2>/dev/null || true

  # Archive originals
  mkdir -p .planning/todos/_archived
  mv .planning/todos/pending .planning/todos/_archived/ 2>/dev/null || true
  mv .planning/todos/done .planning/todos/_archived/ 2>/dev/null || true

  echo "Migrated todos to issues format"
fi

# Ensure in-progress directory exists
mkdir -p .planning/issues/in-progress
```

Migration is idempotent: presence of `_archived/` indicates already migrated.
</step>

<step name="check_exist">
```bash
OPEN_COUNT=$(find .planning/issues/open -maxdepth 1 -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
IN_PROGRESS_COUNT=$(find .planning/issues/in-progress -maxdepth 1 -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
echo "Open issues: $OPEN_COUNT"
echo "In progress: $IN_PROGRESS_COUNT"
```

If both counts are 0:

```
No open or in-progress issues.

Issues are captured during work sessions with /kata-add-issue.

---

Would you like to:

1. Continue with current phase (/kata-track-progress)
2. Add an issue now (/kata-add-issue)
```

Exit.
</step>

<step name="parse_filter">
Check for area filter in arguments:
- `/kata-check-issues` → show all
- `/kata-check-issues api` → filter to area:api only
</step>

<step name="list_issues">
**1. Check GitHub config:**
```bash
GITHUB_ENABLED=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-check-issues/scripts/kata-lib.cjs" read-config "github.enabled" "false")
```

**2. Build dedupe list from local files' provenance fields:**

```bash
# Get all GitHub issue numbers already tracked locally (from open and in-progress)
LOCAL_PROVENANCE=$(grep -h "^provenance: github:" .planning/issues/open/*.md .planning/issues/in-progress/*.md 2>/dev/null | grep -oE '#[0-9]+' | tr -d '#' | sort -u)
```

**3. Query GitHub Issues (if enabled):**

```bash
if [ "$GITHUB_ENABLED" = "true" ]; then
  # Get GitHub Issues with backlog label, excluding those already tracked locally
  # Note: --label flag has issues in some gh CLI versions, use jq filter instead
  GITHUB_ISSUES=$(gh issue list --state open --json number,title,createdAt,labels --jq '.[] | select(.labels[].name == "backlog") | "\(.createdAt)|\(.title)|github|\(.number)"' 2>/dev/null)
fi
```

**4. Query in-progress issues first:**

```bash
for file in .planning/issues/in-progress/*.md; do
  [ -f "$file" ] || continue
  created=$(grep "^created:" "$file" | cut -d' ' -f2)
  title=$(grep "^title:" "$file" | cut -d':' -f2- | xargs)
  area=$(grep "^area:" "$file" | cut -d' ' -f2)
  echo "$created|$title|$area|$file|in-progress"
done | sort
```

**5. Query open issues:**

```bash
for file in .planning/issues/open/*.md; do
  [ -f "$file" ] || continue
  created=$(grep "^created:" "$file" | cut -d' ' -f2)
  title=$(grep "^title:" "$file" | cut -d':' -f2- | xargs)
  area=$(grep "^area:" "$file" | cut -d' ' -f2)
  echo "$created|$title|$area|$file|open"
done | sort
```

**6. Merge and display:**

Display in-progress issues first (if any), then open issues:

- In-progress issues marked with `[IN PROGRESS]` indicator
- Local issues display as-is with their area
- GitHub-only issues (number NOT in LOCAL_PROVENANCE) display with `[GH]` indicator
- Format: `1. [IN PROGRESS] Fix auth bug (api, 2d ago)` or `2. Add feature [GH] (bug, 3d ago)`

Apply area filter if specified. Display as numbered list:

```
Issues:

--- In Progress ---
1. [IN PROGRESS] Fix auth token refresh (api, 2d ago)

--- Open (Backlog) ---
2. Add modal z-index fix (ui, 1d ago)
3. Fix login bug [GH] (bug, 3d ago)
4. Refactor database connection pool (database, 5h ago)

---

Reply with a number to view details, or:
- `/kata-check-issues [area]` to filter by area
- `q` to exit
```

Format age as relative time. The `[GH]` indicator marks GitHub-only issues (not yet pulled to local).
</step>

<step name="handle_selection">
Wait for user to reply with a number.

If valid: load selected issue, proceed.
If invalid: "Invalid selection. Reply with a number (1-[N]) or `q` to exit."
</step>

<step name="load_context">
**If local issue (has file path):**
Read the issue file completely. Display:

```
## [title]

**Area:** [area]
**Created:** [date] ([relative time] ago)
**Files:** [list or "None"]

### Problem
[problem section content]

### Solution
[solution section content]
```

If `files` field has entries, read and briefly summarize each.

**If GitHub-only issue (has [GH] indicator):**
Fetch full issue details from GitHub:

```bash
gh issue view $ISSUE_NUMBER --json title,body,createdAt,labels
```

Display:

```
## [title] [GH]

**Source:** GitHub Issue #[number]
**Created:** [date] ([relative time] ago)
**Labels:** [list of GitHub labels]

### Description
[issue body content]
```

Note: This issue exists only in GitHub, not yet pulled to local.
</step>

<step name="check_roadmap">
```bash
ls .planning/ROADMAP.md 2>/dev/null && echo "Roadmap exists"
```

If roadmap exists:

1. Check if issue's area matches an upcoming phase
2. Check if issue's files overlap with a phase's scope
3. Note any match for action options
   </step>

<step name="offer_actions">
**If in-progress issue:**

Use AskUserQuestion:

- header: "Action"
- question: "This issue is in progress. What would you like to do?"
- options:
  - "Mark complete" — move to closed, close GitHub Issue if linked
  - "Continue working" — show context and begin work
  - "Put back to open" — move back to backlog
  - "View details" — show full issue context

**If GitHub-only issue (has [GH] indicator):**

Use AskUserQuestion:

- header: "Action"
- question: "This is a GitHub Issue. What would you like to do?"
- options:
  - "Pull to local" — create local file for offline work
  - "Work on it now" — pull to local AND move to in-progress (shows mode selection)
  - "View on GitHub" — open in browser (gh issue view --web)
  - "Put it back" — return to list

**If user selects "Work on it now" (for GitHub-only issues):**
First pull to local, then show mode selection (see below).

**If open local issue maps to a roadmap phase:**

Use AskUserQuestion:

- header: "Action"
- question: "This issue relates to Phase [N]: [name]. What would you like to do?"
- options:
  - "Work on it now" — move to in-progress, start working (shows mode selection)
  - "Add to phase plan" — include when planning Phase [N]
  - "Brainstorm approach" — think through before deciding
  - "Put it back" — return to list

**If open local issue with no roadmap match:**

Use AskUserQuestion:

- header: "Action"
- question: "What would you like to do with this issue?"
- options:
  - "Work on it now" — move to in-progress, start working (shows mode selection)
  - "Create a phase" — /kata-add-phase with this scope
  - "Brainstorm approach" — think through before deciding
  - "Put it back" — return to list

**Mode selection (when "Work on it now" selected for open local or GitHub-only issues):**

After selecting "Work on it now", present execution mode selection:

Use AskUserQuestion:

- header: "Execution Mode"
- question: "How would you li