backlog

What this skill does

# Backlog management

Capture single items to a project backlog, or list and triage an existing one. Detect the user's intent and run in either **add** mode (one item being filed) or **review** mode (looking at what's there). The two modes share destination detection.

## Destination detection

Try in order; cache the result for any follow-up in the same flow:

1. `gh repo view` succeeds → use GitHub issues for that repo.
2. Else `docs/BACKLOG.md` exists → append for adds, read for reviews.
3. Else `docs/issues/` directory exists → per-issue files (one `.md` per issue, numbered prefix).
4. Else ask the user where to put it. Don't silently create files in the project root.

If the user invokes this skill in a directory with no obvious project (no git, no `docs/`), say so and ask before doing anything.

## Add mode

The user has a single item to file. Goal: lower ceremony than typing the issue themselves. If it's heavier than that, they'll stop using the skill.

1. **Dupe check.** Search existing items for keyword overlap (`gh issue list --search "<keywords>"` or grep the local file). If a near-match exists, surface it and ask whether to update that one or file new. This is the cheapest defence against ending up with three issues for the same thing.

2. **Enhance proportional to input.** A one-liner from the user warrants 2-3 short context bullets drawn from CLAUDE.md and the current project state (technical caveats, related modules, open questions). If the user already wrote a paragraph or more, file it as-is. Don't restructure their words. The point of enhancement is to capture context they didn't bother to type, not to dress up what they did type.

3. **One clarifying question max**, and only when scope or category (bug vs enhancement) is genuinely ambiguous. If you can guess from context, guess.

4. **File and return the URL or path.** No trailing summary; the URL is the receipt.

### Labels

GitHub: pick from `gh label list`. Don't invent new labels without asking. Projects often have label conventions wired into filters, project boards, or release automation, and an invented label is invisible to those.

Local `docs/BACKLOG.md` or per-issue files: prefix the title with `[bug]` / `[enhancement]` / `[question]` for easy scanning.

## Review mode

The user wants to see what's open and possibly act on something.

1. **List.**
   - GitHub: `gh issue list --state open --limit 50 --json number,title,labels,createdAt`.
   - Local file: read it and parse the bullet/heading structure.
   - Per-issue files: list filenames with their first-line title.

2. **Group and present.** By label first (bug / enhancement / question / other), then by age within each group. One line per item: number, title, age, label. Don't paginate unless the list is genuinely long (>50 items).

3. **Offer three actions** without auto-picking:
   - **Triage**: re-label, close stale items, merge duplicates. Per-item confirmation.
   - **Pick one**: load the full item into context and stop. Do not auto-implement; the user might be scanning the backlog before deciding what to focus on.
   - **Themes**: cluster related items, suggest groupings or parent issues.

The "pick one" action is deliberately a stop point. Sliding into implementation work breaks the user's actual flow, which was reviewing.

## When to redirect

These adjacent skills cover cases this skill should NOT handle. Detect early; if the user's opening line fits one of these, suggest the right skill before doing any work:

- **Multiple items in one go** ("I've found three bugs", "let me run through what's broken") → `qa-to-issues`. The interactive multi-bug interview pattern is what that skill exists for.
- **Full PRD with user stories** ("write up a spec for X", "I want a PRD") → `to-prd`.
- **Breaking an existing plan into slices** ("break this plan into issues", "convert this PRD into tickets") → `to-issues`.

The redirect is a sentence, not a process. Tell the user which skill fits better, then stop.

## Gotchas

- **Don't bulk-close in triage.** "Close the stale ones" almost always means show them first, then close after confirmation. Wrong-close is much more expensive than an extra confirmation step.
- **Don't invent labels.** `gh label list` is cheap; respecting existing label conventions matters because labels drive filters and project boards downstream.
- **Capture must be lighter than typing the issue manually.** The "one clarifying question max" rule isn't about being terse; it's about preserving the value proposition. If the skill takes longer than the user just typing it, they'll stop using it.
- **Per-issue local files need a numbering scheme.** When using `docs/issues/`, look at existing files (`0001-slug.md`? `001-slug.md`?) and continue the existing scheme. Don't impose a new one.
- **Project root pollution.** If no `gh`, no `docs/BACKLOG.md`, no `docs/issues/`, ask. Silently creating `BACKLOG.md` in the project root surprises the user.
- **Don't restructure the user's words.** If they wrote a paragraph, file the paragraph. Reformatting into your preferred template feels like the AI is overwriting their intent, even if the template is "better".
- **Respect issue templates.** If the repo has `.github/ISSUE_TEMPLATE/`, conform the body to the matching template (typically bug vs feature). `gh issue create --title --body` skips templates silently, which surprises maintainers who built filters or automations around the template's fields.