next-action

What this skill does

# Next Action

Find and suggest the next highest-priority action to work on by scanning
multiple task sources (TODO files, source code TODO comments, GitHub issues,
and unpushed local commits), checking for blockers and staleness, and presenting
a recommended action.

This skill **suggests only** — it does not begin working on the task unless the
user explicitly asks.

## Step 1 — Discover task sources

Check the repository root `CLAUDE.md` for any documented task source
configuration. Look for sections or comments that reference:

- TODO file paths (e.g., `TODO.md`, `TASKS.md`, `docs/TODO.md`)
- Issue tracker references (e.g., GitHub Issues, Jira project keys)
- Any custom task source conventions

If no task sources are documented in `CLAUDE.md`:

1. Search for common TODO files at the repo root: `TODO.md`, `TODO`,
   `TASKS.md`, `BACKLOG.md`.
2. Check whether `gh` CLI is available and authenticated (`gh auth status`).
3. If no local TODO file exists and `gh` is not available, ask the user where
   their tasks live. Suggest updating `CLAUDE.md` with a task source
   configuration section like:

   ```markdown
   ## Task Sources
   - Local: TODO.md
   - GitHub Issues: assigned to me, label "ready"
   ```

## Step 2 — Gather candidates from local TODO files

For each discovered TODO file:

1. Read the file contents.
2. Extract all incomplete items (`- [ ] ...`).
3. Parse priority from section headers (`## High Priority`, `## Medium
   Priority`, `## Low Priority`) or inline markers (`P0:`, `P1:`, `P2:`,
   `URGENT:`, `HIGH:`, `MEDIUM:`, `LOW:`).
4. Parse blocker markers: items containing `BLOCKED:`, `BLOCKED BY`, `WAITING
   ON`, or `DEPENDS ON` followed by a description or issue reference are
   considered blocked.
5. **In-progress check** — Detect items already being worked on:
   - Items using an in-progress checkbox marker (`- [~] ...` or `- [-] ...`)
   - Items containing `IN PROGRESS`, `WIP`, or `IN REVIEW` markers
   - Mark these items as in-progress and skip them during recommendation — they
     are likely being handled by another session.
6. **Staleness check** — For each candidate item, check whether referenced files
   or functions still exist:
   - If the item mentions a file path (e.g., `src/auth.go`), verify the file
     exists with `ls`.
   - If the item mentions a function or symbol name, search with `rg` to check
     it still exists in the codebase.
   - If the item references a GitHub issue number (`#123`), check its state
     with `gh issue view <number> --json state --jq '.state'`. Skip items
     referencing closed issues.
   - Flag stale items to the user but do not recommend them.

## Step 3 — Gather candidates from source code TODO comments

Run the helper script to scan and score inline TODO comments:

```bash
bash "${SKILL_DIR}/scan-code-todos.sh" --limit 20 .
```

where `${SKILL_DIR}` is the directory containing this SKILL.md file.

The script scans for `TODO`, `FIXME`, `HACK`, and `XXX` comments in source code
(excluding markdown, JSON, lock files, vendored/generated directories), parses
each match into structured JSON with fields: `tag`, `tracker_id`, `assignee`,
`description`, `file`, `line`, and `score`.

Scoring rules applied by the script:

- `FIXME` / `XXX` → 80
- `HACK` → 60
- `TODO` with `P0` / `URGENT` marker → 70
- `TODO` with tracker ID → 50
- plain `TODO` → 35
- Security keywords (`security`, `vulnerability`, `crash`, `data loss`,
  `race condition`) boost score to 80

**Post-processing (after receiving script output):**

1. **Deduplication** — If a TODO comment references a tracker ID that matches a
   GitHub issue gathered in Step 4, merge them: attach the code location to the
   GitHub issue candidate rather than creating a duplicate entry.  If multiple
   TODO comments share the same tracker ID, group them as a single candidate
   with multiple locations.

2. **Staleness check** — If a comment references a GitHub issue (`#123` in the
   `tracker_id` field), check its state with `gh issue view`. If the issue is
   closed, the TODO is stale — flag it as needing cleanup rather than
   recommending it as work.

## Step 4 — Gather candidates from GitHub Issues

Run the helper script to fetch and score open GitHub issues:

```bash
bash "${SKILL_DIR}/scan-github-issues.sh" --limit 20
```

where `${SKILL_DIR}` is the directory containing this SKILL.md file.

The script handles:

- Fetching open issues assigned to the current user and unassigned open issues,
  deduplicating the combined set
- Parsing priority signals from labels (`P0`, `P1`, `critical`, `urgent`,
  `high-priority`, `good first issue`, `help wanted`) and title prefixes
  (`[P0]`, `[URGENT]`, etc.)
- **Blocker detection** — task list references (`- [ ] #123`), URL references
  (`- [ ] https://github.com/.../issues/123`), and keywords (`blocked by #123`,
  `depends on #123`). Each referenced issue is checked; if still open, the
  issue is marked blocked.
- **In-progress detection** — issues with `in progress`, `wip`, `in-progress`,
  or `in review` labels, and issues with linked open pull requests.
- Scoring per the table in Step 6, including the `+15` assignment bonus.

Output: JSON array sorted by score (descending), each entry:

```json
{"number": 7, "title": "...", "labels": [...], "score": 55, "status": "ready", "blocked_by": [], "assignees": [...]}
```

Status values: `"ready"`, `"blocked"`, `"in_progress"`.

**Post-processing (after receiving script output):**

1. **Staleness check** — For each issue with status `"ready"`, search the
   codebase for references:

   ```bash
   rg '#<issue-number>\b' .
   rg 'issues/<issue-number>\b' .
   ```

   If the issue references specific files, functions, or code paths in its
   body, verify they still exist. Flag issues whose context has significantly
   changed.

## Step 5 — Review unpushed local commits

Check for commits on the current branch that have not been pushed to the remote.
These represent completed work that still needs to be pushed, or issues that
were addressed locally but whose corresponding GitHub issues remain open.

1. Detect unpushed commits by running the helper script:

   ```bash
   bash "${SKILL_DIR}/unpushed-commits.sh"
   ```

   where `${SKILL_DIR}` is the directory containing this SKILL.md file.

   The script tries three strategies in order: the upstream tracking ref,
   the same branch name on origin, and the remote default branch. This
   handles local branches that have no upstream configured — a common case
   for new feature branches.

   If the script produces no output, there are no unpushed commits — skip
   this step.

2. For each unpushed commit, extract the commit subject and check:
   - **Issue references** — If the commit message references a GitHub issue
     (`#123`, `fixes #123`, `closes #123`, `resolves #123`), record the
     association. These issues may be resolved locally but not yet closed on
     GitHub because the commits haven't been pushed.
   - **Conventional commit scope** — Parse the commit type and scope (e.g.,
     `feat(auth): ...`, `fix(parser): ...`) to understand what area was changed.

3. Cross-reference unpushed commits with GitHub issues:
   - For each issue number referenced in unpushed commit messages, check
     whether the issue is open:
     ```bash
     gh issue view <number> --json state --jq '.state'
     ```
     This lookup is self-contained — it does not depend on the GitHub issue
     candidates gathered in Step 4. This allows `/next-action unpushed` to
     work as a standalone mode without running the full GitHub issues scan.
   - If an unpushed commit references an open issue via a closing keyword
     (`fixes #N`, `closes #N`, or `resolves #N`), mark that issue as
     **locally resolved — needs push**. Do not recommend it as work to do;
     instead, surface it as a push action.
   - If an unpushed commit references an open issue but without a closing
     keyword (just `#N`), flag the issue as **partially addressed