# Work Backlog Item

> Use when working, planning, or closing a backlog item. Bridges backlog items to the SAM planning pipeline with optional GitHub Issue/Project/Milestone tracking. No args: interactive browser. With '#N': load item directly from GitHub Issue #N (labels and milestone are canonical status). With title substring: auto-grooming, RT-ICA gate, GitHub issue sync, SAM planning, plan reference recorded. '--auto {title}': fully autonomous mode — no AskUserQuestion calls, derives missing data from research files, logs all decisions, skips interactive GitHub prompts; suitable for agent use without human in the loop. 'close {title}': verifies plan checklist 100% complete, closes GitHub issue, marks DONE. 'resolve {title}': marks item no longer applicable with reason. 'setup-github': initializes labels, creates project and first milestone. Optional '--language {python|typescript|...}' and '--stack {python-fastapi|python-cli|...}' select Layer 1/2 profile. STOPS if item has existing Plan field or RT-ICA returns BLOCKED.

- Skill: `tools-only/work-backlog-item` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add tools-only/work-backlog-item`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/work-backlog-item/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/tools-only/work-backlog-item

---

# Work Backlog Item

Bridge a backlog item into the SAM planning pipeline via `/python3-development:add-new-feature` (default). Optional `--language` and `--stack` select Layer 1/2 profiles — see [.claude/docs/sdlc-layers/](../../docs/sdlc-layers/).

**Phase separation**: Grooming (Step 3) is autonomous research — the agent verifies facts, maps resources, estimates effort, and surfaces blockers. Planning (Step 6) is solution design — architecture, tasks, implementation. The human sets priorities and resolves blockers; the agent handles research and fact-checking autonomously.

**SAM** — Stateless Agent Methodology. See [sam-definition.md](./references/sam-definition.md) for what SAM is and how to embody it. SAM lives in `../stateless-agent-methodology/` (or `bitflight-devops/stateless-agent-methodology` on GitHub).
Primary source of truth is **GitHub Issues** (labels + milestone = canonical status); `.claude/backlog/` per-item files are the local cache and are kept in sync.

When invoked with no arguments, shows an interactive browser. When invoked with `#N` or a title substring, proceeds directly to the planning workflow.

## Arguments

`$0` selects the operating mode; remaining positional args (`$1`, `$2`, ...) form the title or parameter:

| `$0` value | Remaining args | Mode |
|---|---|---|
| (empty) | — | Interactive browser |
| `#N` | — | Issue-first: load item from GitHub Issue #N |
| `--auto` | `$1`+ = title (or empty → auto-select first open P0/P1 item) | Autonomous — no `AskUserQuestion` calls |
| `close` | `$1`+ = title or `#N` | Verify and close a completed item |
| `resolve` | `$1`+ = title or `#N` | Mark no longer applicable (reason required) |
| `setup-github` | — | Initialize labels, project, first milestone |
| (any other) | — | `$ARGUMENTS` treated as title substring → planning |

**Optional flags** (when `$0` is title substring or `--auto`): `--language <lang>` selects language plugin (default: python); `--stack <profile>` selects stack profile (e.g., python-fastapi, python-cli). See [.claude/docs/sdlc-layers/](../../docs/sdlc-layers/).

```text
/work-backlog-item                                    # interactive browser
/work-backlog-item #42                               # issue-first → planning
/work-backlog-item Error Recovery                    # direct match → planning
/work-backlog-item --auto                            # autonomous → auto-select first open P0/P1
/work-backlog-item --auto vercel skills npm package  # autonomous → planning
/work-backlog-item close Error Recovery              # verify and close by title
/work-backlog-item close #42                         # verify and close by issue number
/work-backlog-item resolve commitlint                # mark no longer applicable
/work-backlog-item resolve #17                       # mark no longer applicable by issue
/work-backlog-item --language python --stack python-fastapi Add auth  # Layer 2 stack profile
```

### --auto mode rules

When `$0` is `--auto`, the following substitutions apply at every interactive decision point:

| Normal behaviour | `--auto` substitution |
|---|---|
| No title given (`$1` is empty) | Scan `.claude/backlog/` per-item files for P0 then P1 items that have status `needs-grooming` or `groomed` (not `done`, `resolved`, or `closed`). Log `[AUTO] No title — auto-selected: {title}`, use that item's title as the working title and proceed. If no open P0/P1 item exists, log `[AUTO] STOP — no open P0/P1 items found` and stop. |
| Step 1b: issue not found | Log `[AUTO] STOP — Issue #N not found`, stop |
| Step 1: zero matches → ask user to create | Auto-invoke `create-backlog-item --auto {title}`, log `[AUTO] No item found — invoking create-backlog-item --auto` |
| Step 1: multiple matches → ask user to pick | Log `[AUTO] Multiple matches — picking first: {title}`, proceed with first match |
| Step 2.5: offer GitHub issue for P0/P1 | Log `[AUTO] Skipping GitHub issue offer`, continue without issue |
| Step 2.5: ask milestone assignment | Log `[AUTO] Skipping milestone assignment`, skip |
| RT-ICA BLOCKED | Log `[AUTO] STOP — RT-ICA BLOCKED: {missing inputs}`, stop (cannot resolve without human) |
| Any other `AskUserQuestion` | Log `[AUTO] Decision: {chosen option} — reason: {evidence}`, proceed with logged choice |

`--auto` does NOT change the behaviour of Steps 3–8 (grooming, RT-ICA evaluation, SAM planning, backlog update) — those are already agent-executable without human input.

## Workflow

### Routing (evaluated first, before any step)

Dispatch based on `$0` (the first argument word) before executing any step:

| `$0` value | Title source | Route |
|---|---|---|
| (empty) | — | Step 0 — interactive browser |
| `#N` (starts with `#`) | issue number | Step 1b — Issue-first path |
| `--auto` | `$1`+ joined (empty → auto-select first open P0/P1) | AUTO_MODE=true → Step 1 |
| `close` | `$1`+ joined (title or `#N`) | Step 9 (close path) |
| `resolve` | `$1`+ joined (title or `#N`) | Step 9 (resolve path) |
| `setup-github` | — | setup-github command |
| (any other) | `$ARGUMENTS` | Title substring → Step 1 (interactive mode) |

**AUTO_MODE** — when set, all `AskUserQuestion` calls are replaced with evidence-derived decisions. See the `--auto mode rules` table in the Arguments section for each substitution.

### Step 0: Interactive Browser (no arguments only)

**Trigger:** `$0` is empty (no arguments passed).

<step0_procedure>

1. Invoke the backlog script to list items with status:

   ```bash
   uv run .claude/skills/backlog/scripts/backlog.py list --format json --with-status -R Jamie-BitFlight/claude_skills
   ```

   Parse the JSON output. Each entry has `section`, `title`, `issue`, `plan`, `status`, `milestone`, `file_path` (index format), `groomed` (true if item has groomed content).

2. **Groomed** = item has `groomed: true` in JSON, or `## Groomed` section in its per-item file (`.claude/backlog/{priority}-{slug}.md`). Read the item file; if groomed sections present, use them.

3. Present a numbered list. Use these status indicators in user-visible output only:

   ```text
   Backlog Items:

   P0
     1. ✅ SAM: Error Recovery / Rollback Procedures       [#12  status:in-progress  v1.0]
     2. 🔍 SAM: Regex False Positive Suppression           [#14  status:needs-grooming  v1.0]

   P1
     3. 📋 SAM: Validate Task File Schema                  [no issue]
     4. 📋 SAM: Implement Feature Dry-Run Mode             [no issue]

   P2
     5. 🔍 SAM: Context Window Budget Tracking             [#18  status:needs-grooming  —]

   Ideas
     6. 📋 SAM: Multi-Repo Support                         [no issue]

   Status: ✅ = planned/in-progress  🔍 = groomed/needs-grooming  📋 = not yet groomed

   Options:
     [number]   — Select item to work on
     G [number] — Groom a specific item
     G all      — Groom all ungroomed items
     D [number] — Show full details for an item
   ```

4. Use `AskUserQuestion` to ask: "Which item would you like to work on next?"

5. Handle the response:
   - `[number]` — use that item's title as the working title and proceed to Step 1
   - `G [number]` — invoke `Skill(skill="groom-backlog-item", args="{item title}")` then re-display the list
   - `G all` — invoke `Skill(skill="groom-backlog-item", args="all")` then re-display the list
   - `D [number]` — display the full item description, research_first field, and groomed content (if present in the item file under `## Groomed`), then re-display the list
   - `C [number]` — proceed to Step 9 (close path) with that item's title
   - `R [number]` — proceed to Step 9 (resolve path) with that item's title

</step0_procedure>

**Routing:** If `$0` is `close` or `resolve`, extract `$1`+ as the title and jump directly to Step 9.

### Step 1b: Issue-First Path (`#N`)

**Trigger:** `$0` matches `#[0-9]+`.

<issue_first_procedure>

Extract the issue number `{issue_number}` from `$0`. Fetch the issue:

```bash
gh issue view {issue_number} -R Jamie-BitFlight/claude_skills \
  --json number,title,state,body,labels,milestone
```

If the issue does not exist, report and stop.
If the issue is already closed, warn: "Issue #{issue_number} is closed. Use `close` or `resolve` if needed." and stop.

From the issue response build the working item:

| Field | Source |
|---|---|
| `title` | issue `title` |
| `description` | issue `body` (full text) |
| `source` | `"GitHub Issue #N"` |
| `priority` | `priority:*` label → P0 / P1 / P2 / Ideas |
| `status` | `status:*` label (canonical — GitHub labels are authoritative for status) |
| `milestone` | issue `milestone.title` |
| `plan` | search `body` for `**Plan**:` line |

Then try to find a matching per-item file in `.claude/backlog/` by issue number (`metadata.issue`) or title. If found, use it to supplement any missing fields (e.g. `research_first`, `suggested_location`). If not found, continue without a local per-item file — the GitHub Issue is sufficient.

Proceed to Step 2.7 (Set In-Progress Label) with the assembled item, then continue to Step 3.

</issue_first_procedure>

### Step 1: Find the Backlog Item

Run `uv run .claude/skills/backlog/scripts/backlog.py list --format json` and search the `title` field of each entry for a case-insensitive match against the title. Title = `$1`+ joined (args after the mode flag `$0`). In interactive mode, title = full `$ARGUMENTS`.

**AUTO_MODE with no title (`$1` is empty):** apply the "No title given" substitution from the `--auto mode rules` table — scan P0 then P1 sections for the first open item, log and use its title. Skip items with `status: done` or `status: resolved` in their JSON entry (these are filtered out by `backlog.py list` already).

- **Zero matches (interactive mode):** report "No backlog item found matching: {title}" and offer to create one via `/create-backlog-item`.
- **Zero matches (AUTO_MODE):** log `[AUTO] No item found — invoking create-backlog-item --auto {title}`, invoke `Skill(skill: "create-backlog-item", args: "--auto {title}")`, then re-run Step 1.
- **Multiple matches (interactive mode):** list all matches and ask the user to pick one.
- **Multiple matches (AUTO_MODE):** log `[AUTO] Multiple matches — picking first: {title}`, proceed with first match.

Record the priority section (P0, P1, P2, Ideas) the item belongs to.

### Step 2: Extract Item Fields

From the matched item's JSON output (via `backlog.py list --format json`), extract `title`, `plan`, `section` (priority), `issue`, `groomed`, and `file_path`. For detailed fields not in JSON (`description`, `source`, `added`, `research_first`, `suggested_location`), read the per-item file at `file_path`.

- `title` — the `title` field from JSON (required)
- `source` — not in JSON; read from per-item file frontmatter `metadata.source` if needed (optional)
- `added` — not in JSON; read from per-item file frontmatter `metadata.added` if needed (optional)
- `description` — not in JSON; read from per-item file frontmatter `description` (required)
- `research_first` — not in JSON; read from per-item file body `**Research first**:` line (optional)
- `suggested_location` — not in JSON; read from per-item file body `**Suggested location**:` line (optional)
- `plan` — the `plan` field from JSON (optional)

If the item already has a `**Plan**:` field, report:

```text
This item already has a plan at {path}. Use /python3-development:implement-feature {path} to execute it.
```

Then stop.

After extracting fields, proceed to Step 2.5 (GitHub Issue Sync) before continuing to Step 3.

### Step 3: Auto-Groom (if needed)

<groom_check>

1. **Check if item is groomed**: Check the `groomed` field in the JSON output. If `true`, read the per-item file at `file_path` for the groomed content under `## Groomed`. Use that content.
2. Search conversation context for a recent `groom-backlog-item` output matching this item.

If no groomed content exists in the item file:

```text
Skill(skill: "groom-backlog-item", args: "{item title}")
```

The groom skill writes groomed content into the per-item file. Capture the groomed output (Reproducibility, Resources, Dependencies, Blockers, etc.) for use in the feature request.
</groom_check>

### Step 4: RT-ICA Checkpoint

<rtica_gate>
Before composing the feature request, verify the groomed content (from item file or groom-backlog-item output) contains an RT-ICA summary. If absent, perform RT-ICA now:

1. **Goal statement** — What completing this item achieves.
2. **Reverse prerequisites** — Conditions required for success (enumerate each).
3. **Availability check** — For each condition: AVAILABLE / DERIVABLE / MISSING.
4. **Decision** — APPROVED or BLOCKED.

**If BLOCKED:**

When RT-ICA blocks, optionally offer ARL human-probing questions (e.g., "What went wrong in the past?", "What references are essential?") to capture invisible knowledge. Add answers to `.claude/domain-knowledge/` with staleness tracking. See [.claude/docs/sdlc-layers/arl-human-probing-design.md](../../docs/sdlc-layers/arl-human-probing-design.md).

Present a structured summary to the user:

```text
RT-ICA: BLOCKED

Missing inputs that prevent SAM planning:
- {missing condition 1}
- {missing condition 2}

Provide these inputs before proceeding. SAM planning will not be invoked with known gaps.
```

Wait for user response. Do not invoke Step 5 until BLOCKED is resolved.

**If APPROVED:**

Proceed to Step 5. Carry DERIVABLE items forward as "Assumptions to confirm" in the RT-ICA section of the feature request.
</rtica_gate>

### Step 5: Compose Feature Request

Build the feature request string for `add-new-feature`. If `--stack` was specified, append a "Stack profile" line to the feature request. If `--language` was specified and is not `python`, invoke the corresponding language plugin (e.g., `/typescript-development:add-new-feature` for `typescript`).

```text
## Backlog Item: {title}

**Source**: {source}
**Priority**: {priority section — P0/P1/P2/Ideas}
**Added**: {added date}

### Description

{description text}

### Research Questions

{research_first text, or "None" if absent}

### Suggested Location

{suggested_location text, or "To be determined during architecture phase" if absent}

### RT-ICA Assessment

**Decision**: APPROVED
**Goal**: {goal statement}
**Verified conditions**: {list of AVAILABLE items}
**Assumptions to confirm**: {list of DERIVABLE items, or "None"}

### Grooming Context

{full context manifest from Step 3, if available}

### Stack Profile (optional)

{stack profile name if --stack specified, e.g., python-fastapi}
```

### Step 6: Invoke SAM Planning

```text
Skill(skill: "python3-development:add-new-feature", args: "{composed feature request}")
```

This runs the full SAM workflow: discovery, codebase analysis, architecture spec, task decomposition, validation, context manifest.

### Step 7: Update Backlog with Plan Reference

After `add-new-feature` completes, identify the task file it created:

```text
Glob(pattern="plan/tasks-*-{slug}*")
```

Where `{slug}` is the item title lowercased with spaces replaced by hyphens.

Invoke the backlog script to add the Plan:

```bash
uv run .claude/skills/backlog/scripts/backlog.py update "{title}" --plan "plan/tasks-{N}-{slug}.md" -R Jamie-BitFlight/claude_skills
```

If the item has `**Issue**: #N`, record it in the plan file header comment and include `Fixes #N` in any commit message produced during implementation.

### Step 8: Report Next Steps

```text
Backlog item "{title}" is now planned.

- Plan file: plan/tasks-{N}-{slug}.md (or plan/tasks-{N}-{slug}/ directory)
- To execute:      /python3-development:implement-feature {slug}
- To check status: /python3-development:implementation-manager status . {slug}
- To close when done: /work-backlog-item close {slug}
```

**Do NOT close the GitHub Issue directly.** Include `Fixes #N` in commit messages and the PR body — the issue auto-closes when the PR merges. Only use `/work-backlog-item close` for post-merge verification and local bookkeeping. Never invoke `backlog.py close` before the PR has merged.

### Step 9: Verify and Close

**Trigger:** `$0` is `close` or `resolve`.

<step9_procedure>

Extract the operation from `$0` and the argument from `$1`+:

- `$0` = `close`: `$1`+ = title or `#N` → verify implementation and mark COMPLETED
- `$0` = `resolve`: `$1`+ = title or `#N` → mark no longer applicable (no verification required)

#### 9a: Find Item

If `$1` starts with `#` (e.g., `close #42`), treat it as an issue number:

```bash
gh issue view {issue_number} -R Jamie-BitFlight/claude_skills \
  --json number,title,state,body,labels
```

- If the issue is not found, report and stop.
- Extract `title` from the issue response and use it as the working title.

Otherwise, scan `.claude/backlog/` per-item files and search item titles for case-insensitive match against `{title}`.

- Zero matches: report "No backlog item found matching: {title}" and stop.
- Multiple matches: list all matches and ask user to pick one.
- Item already in `## Completed` section: report "Item already closed on {Completed date}" and stop.

#### 9b: Resolve path (skip verification)

If operation is `resolve`:

1. Use `AskUserQuestion` to ask: "Why is this item no longer applicable?" (free text)
2. Invoke the backlog script:

```bash
uv run .claude/skills/backlog/scripts/backlog.py resolve "{title or #N}" --reason "{reason}" -R Jamie-BitFlight/claude_skills
```

3. Report the script output to the user.

Then stop.

#### 9c: Close path — checklist verification

If operation is `close`:

1. Extract `**Plan**:` field from the matched item. If absent:

```text
No plan file recorded for "{title}". Cannot verify checklist.
Either run /work-backlog-item {title} first to create a plan,
or use /work-backlog-item resolve {title} if no plan was needed.
```

Then stop.

2. Read the plan file. Count:
   - `total_tasks` — lines matching `- \[ \]` or `- \[x\]`
   - `checked_tasks` — lines matching `- \[x\]`

3. If `checked_tasks < total_tasks`:

```text
Checklist incomplete: {checked_tasks}/{total_tasks} tasks done.

Remaining:
{list of unchecked task lines}

Complete all tasks before closing this item.
```

Then stop.

#### 9d: Close path — acceptance criteria verification

4. Spawn a verification agent:

```text
Task(
  subagent_type: "general-purpose",
  prompt: "You are verifying whether a completed backlog item genuinely satisfies its stated goal.

Backlog item title: {title}
Description and acceptance criteria:
{description text from per-item file}

Plan file: {plan file path}
Plan checklist: {checked_tasks}/{total_tasks} — 100% complete.

Your task:
1. Read the plan file to understand what was implemented.
2. Search git log for commits referencing this item (use: git log --oneline -20).
3. Read 2-3 key changed files to verify the implementation exists.
4. Assess: Does the implementation satisfy the stated goal? Is the product better for it?

Return:
- PASS or FAIL
- One sentence of evidence (file:line or commit SHA)
- Any gaps you found (if FAIL)"
)
```

5. Collect agent verdict:
   - **PASS**: proceed to 9e
   - **FAIL**: report gaps, do not close:

```text
Verification FAILED for "{title}".

Gaps found:
{agent findings}

Address these gaps before closing.
```

Then stop.

#### 9e: Check for open PR

6. If the item has a linked GitHub Issue (`#N`), check whether an open PR already references it:

```bash
gh pr list -R Jamie-BitFlight/claude_skills --search "Fixes #N" --state open --json number,title,url
```

- **Open PR found**: The PR body contains `Fixes #N` — the issue will auto-close on merge. Update only the local per-item file status (do NOT close the GitHub Issue):

```bash
uv run .claude/skills/backlog/scripts/backlog.py update "{title}" --status in-progress -R Jamie-BitFlight/claude_skills
```

Report:

```text
Backlog item "{title}" verified. GitHub Issue #{N} will auto-close when PR #{pr_number} merges.
```

Then stop.

- **No open PR / no linked issue**: proceed to 9f.

#### 9f: Invoke backlog close

7. Invoke the backlog script (script updates per-item file and closes GitHub issue):

```bash
uv run .claude/skills/backlog/scripts/backlog.py close "{title}" --plan "{plan file path}" --checklist-pass -R Jamie-BitFlight/claude_skills
```

If invoked as `close #N`, use `#N` as the selector:

```bash
uv run .claude/skills/backlog/scripts/backlog.py close "#{N}" --plan "{plan file path}" --checklist-pass -R Jamie-BitFlight/claude_skills
```

8. Report the script output to the user.

</step9_procedure>

## GitHub Integration

`.claude/backlog/` per-item files are the local cache. GitHub Issues are the source of truth. They are linked — when you work a P0/P1 backlog item, a GitHub Issue is created and kept in sync.

```text
.claude/backlog/    →  GitHub Issue
  metadata.priority →  priority:* label
  Description       →  Issue body (story format)
  metadata.status   →  status:* label
  metadata.plan     →  Issue body Notes
  metadata.issue    ←  written back after creation
  metadata.status   →  Issue closed
```

Full step-by-step commands and example sessions: [github-integration.md](./references/github-integration.md)

### Commit Messages and PR Body — `Fixes #N`

When implementing a backlog item that has a linked GitHub Issue (`**Issue**: #N`), **every commit and the PR description MUST reference the issue** so GitHub auto-closes it on merge:

- **Commit messages**: end the subject line with `(fixes #N)` or add a `Fixes #N` footer in the body:
  ```text
  fix(perl-development): replace shell injection in run_command (fixes #80)
  ```
  or
  ```text
  fix(perl-development): replace shell injection in run_command

  Fixes #80
  ```
- **PR description**: include at least one `Fixes #N` line in the PR body so GitHub links and auto-closes the issue when the PR is merged.
- When a PR fixes **multiple issues**, list each on a separate line:
  ```text
  Fixes #80
  Fixes #83
  ```
- Use `Fixes` (not `Closes`) for bugs and security issues; either works for feature work.

This convention ensures issues are automatically closed on merge without manual intervention.

### Step 2.5: GitHub Issue Sync

After Step 2, check for `**Issue**: #N` field in the matched item.

- Found: verify issue state with `gh issue view {issue_number} -R Jamie-BitFlight/claude_skills --json number,title,state,labels`
- Not found + P0/P1: offer to create a GitHub Issue (proceed to Step 2.5a)
- Not found + P2/Ideas: skip silently

### Step 2.5a: Create GitHub Issue

Invoke the backlog script:

```bash
uv run .claude/skills/backlog/scripts/backlog.py update "{title}" --create-issue -R Jamie-BitFlight/claude_skills
```

The script creates the issue and writes `issue: '#N'` back to the per-item file frontmatter.

### Step 2.7: Set In-Progress Label

If the item has `**Issue**: #N`, invoke the backlog script:

```bash
uv run .claude/skills/backlog/scripts/backlog.py update "{title}" --status in-progress -R Jamie-BitFlight/claude_skills
```

If the item is in a milestone with other issues, also run `milestone start` for the milestone:

```bash
uv run .claude/skills/gh/scripts/github_project_setup.py milestone start \
  --number {milestone_number} --repo Jamie-BitFlight/claude_skills
```

### setup-github Command

**Trigger:** `$0` is `setup-github`. Initializes label taxonomy, first milestone, and GitHub Project.

```bash
uv run .claude/skills/gh/scripts/github_project_setup.py labels --repo Jamie-BitFlight/claude_skills
gh api repos/Jamie-BitFlight/claude_skills/milestones -X POST \
  -f title="v1.0 — Skills Foundation" -f due_on="2026-03-31T00:00:00Z"
gh project create --owner Jamie-BitFlight --title "claude_skills Backlog"
```

Full setup steps and expected output: [github-integration.md](./references/github-integration.md)

## Error Handling

- `#N` not found: report and list open issues with `gh issue list -R Jamie-BitFlight/claude_skills --state open`
- `#N` already closed: warn and stop; offer `close` or `resolve` if needed
- `close #N` / `resolve #N` — issue not found: report and stop
- Item not found: list available items from `.claude/backlog/` per-item files with their priority sections
- Multiple matches: present numbered list, ask user to choose
- Grooming fails: proceed without grooming context, note the gap in the feature request
- RT-ICA returns BLOCKED: present missing inputs, wait for user, do not invoke `add-new-feature`
- `add-new-feature` fails: report the failure, do not update per-item file
- Plan file not found after planning: search `plan/` directory broadly, ask user to confirm the path
- Grooming reports directory does not exist: treat all items as ungroomed
- `close` with no `**Plan**:` field: report and offer `resolve` as alternative
- `close` with incomplete checklist: list remaining tasks, do not close
- `close` with verification FAIL: report gaps, do not close
- `close` on already-completed item: report closed date, do not re-close
- `resolve` with no reason provided: block until user provides reason (reason is required evidence)
- GitHub issue creation fails: report error, continue with per-item-file-only workflow; do not block SAM planning
- `gh` not installed: run `uv run .claude/skills/gh/scripts/setup_gh.py` first
- Label not found during issue create: `github_project_setup.py` creates it automatically
- Milestone not found: skip milestone assignment; do not fail

## Example Sessions

### Issue-first planning (`#N`)

```text
> /work-backlog-item #131

Loading GitHub Issue #131...
  Title:     plugin-validator: UX and coverage gaps
  Labels:    priority:p1, status:needs-grooming
  Milestone: v1.1 — Quality Gates
  State:     open

Matched per-item file for additional context: ✓
No groomed content in item file. Running groom-backlog-item first...

[groomed content written to item file]

RT-ICA: APPROVED — all conditions available.
Setting status:in-progress on issue #131...
  ✓ status:needs-grooming → status:in-progress

Composing feature request...
Invoking /python3-development:add-new-feature...

[SAM phases run]

Updated per-item file with Plan: plan/tasks-2-validator-ux-coverage.md

Next steps:
- To execute:      /python3-development:implement-feature validator-ux-coverage
- To close when done: /work-backlog-item close plugin-validator UX and coverage gaps
```

### Planning (with title substring)

```text
> /work-backlog-item Error Recovery

Found: "SAM: Error Recovery / Rollback Procedures" (P1)
No groomed content in item file. Running groom-backlog-item first...

[groomed content written to item file]

RT-ICA: APPROVED — all conditions available.
Composing feature request...
Invoking /python3-development:add-new-feature...

[SAM phases run]

Updated per-item file with Plan: plan/tasks-2-error-recovery.md

Next steps:
- To execute:      /python3-development:implement-feature error-recovery
- To check status: /python3-development:implementation-manager status . error-recovery
- To close when done: /work-backlog-item close error-recovery
```

### Closing a completed item (by title)

```text
> /work-backlog-item close validator UX

Found: "plugin-validator UX and coverage gaps" (P1)
Plan: plan/tasks-2-validator-ux-coverage.md
Checklist: 12/12 tasks complete

Spawning acceptance criteria verification agent...

Verdict: PASS
Evidence: Sub-issues 1-4 implemented in plugins/plugin-creator/scripts/plugin_validator.py
          commit 4a2f1b3 — "fix(validator): report unique files, add hook validation"

Backlog item "plugin-validator UX and coverage gaps" closed.
- Checklist: 12/12 tasks complete
- Acceptance criteria: PASS
- Status written to per-item file
```

### Closing a completed item (by issue number)

```text
> /work-backlog-item close #131

Fetching GitHub Issue #131...
  Title: plugin-validator UX and coverage gaps
  State: open

Found per-item file match: "plugin-validator UX and coverage gaps" (P1)
Plan: plan/tasks-2-validator-ux-coverage.md
Checklist: 12/12 tasks complete

Spawning acceptance criteria verification agent...

Verdict: PASS
Evidence: commit 4a2f1b3 — "fix(validator): report unique files, add hook validation"

Backlog item "plugin-validator UX and coverage gaps" closed.
- Checklist: 12/12 tasks complete
- Acceptance criteria: PASS
- Status written to per-item file
- GitHub Issue #131 closed
```

### Resolving a no-longer-applicable item

```text
> /work-backlog-item resolve commitlint verify last flag

Found: "commitlint: Verify --last flag and exit codes against primary sources" (P1)
Why is this item no longer applicable?
> REFUTED by fact-check: --last flag is verified in commitlint source cli.ts. No fix needed.

Backlog item resolved.
  Resolved: 2026-02-21
  Status: RESOLVED — REFUTED by fact-check: --last flag verified against commitlint
          source cli.ts and official docs. No fix needed.
```

GitHub-specific example sessions (issue creation flow and setup-github): [github-integration.md](./references/github-integration.md)

---

## Validation Plan

See [validation-plan.md](./references/validation-plan.md) for V1–V6 verification commands and the full integration test sequence.