Issue

---
name: issue
description: Creates issues from a natural language description — single or batch — and auto-updates related planning and design docs.
argument-hint: '[issue description]'
disable-model-invocation: false
allowed-tools: Task, Read, Glob, Grep, Write, Edit, Bash
---
<!-- AUTO-GENERATED by scripts/gen_skills.py — DO NOT EDIT. Edit SKILL.md.tmpl instead. -->

## Kit Preamble — issue

### Kit Script Root
Kit root: `${CLAUDE_PLUGIN_ROOT}`
- Absolute path above → plugin install (substituted at load time; no project
  `scripts/` dir): prefix every kit script command with it, e.g.
  `bash <kit-root>/scripts/checkpoint.sh …`. Absolute paths also work from worktrees.
- Literal `${…}` placeholder above → standalone layout: run commands as written.

### Project Context Detection
Run these checks silently at the start. Use results to adapt behavior:
- `[ -f issues.md ]` — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
- `[ -f docs/sprint_state.md ]` — if true and Status shows `running`, a sprint is active. Be aware of parallel work in worktrees.
- `[ -f docs/prd_digest.md ]` — if true, read it for quick project context before starting.

### Kit Rules
- Verify `gh auth status` before any GitHub operation.
## Algorithm

### Phase 1 — Context Gathering

1) Read `$ARGUMENTS`. If empty, ask the user for a description and stop.
2) Read `issues.md`. If not found, tell the user to run `/kickoff` first and stop.
3) Parse the highest issue number from `issues.md` using `### ISSUE-(\d+):` regex. Next issue number = max + 1.
4) Read the following docs in **parallel** (skip any that don't exist):
   - `docs/prd_digest.md`
   - `docs/requirements.md`
   - `docs/ux_spec.md`
   - `docs/architecture.md`
   - `docs/data_model.md`
   - `docs/test_plan.md`
   - `docs/design_philosophy.md`
   - `docs/design_system.md`
   - `docs/wireframes.md`
   - `docs/interactions.md`
   - `docs/copy_guide.md`

If none of the planning docs exist, warn the user but proceed with `issues.md` + `STATUS.md` only.

4.5) Set design context flag:
   - `has_design_docs` = `true` if **both** `docs/design_philosophy.md` and `docs/wireframes.md` exist; `false` otherwise.
   - This flag controls whether design doc updates are offered in Phase 2.

### Phase 2 — Doc Update Detection & Scope Estimation

5) Analyze the natural-language description against existing planning docs to determine which docs need updating:

   **Planning docs** (always evaluated):
   - `issues.md` — always
   - `STATUS.md` — always
   - `docs/requirements.md` — when the description introduces requirements not covered by existing FRs/NFRs
   - `docs/ux_spec.md` — when the description involves UI elements, screens, user flows, or interactions
   - `docs/architecture.md` — when the description involves new modules, services, APIs, or infrastructure changes
   - `docs/data_model.md` — when the description involves new entities, fields, or schema changes
   - `docs/test_plan.md` — when the description introduces new test flows or critical paths

   **Design docs** (only when `has_design_docs` is true):
   - `docs/design_system.md` — when the description requires new UI components not in the existing system
   - `docs/wireframes.md` — when the description introduces new screens or significantly modifies existing screen layouts
   - `docs/interactions.md` — when the description introduces new user flows, transitions, or interaction states
   - `docs/copy_guide.md` — when new screens or states need UI copy definitions
   - `docs/design_philosophy.md` — **read-only reference**. If the new feature conflicts with the existing design philosophy (e.g., gamification in a minimalist product), FLAG this as a warning and suggest running `/uiux` to revisit the design direction. Do NOT modify this file.

6) **Estimate issue count**:
   - If the description maps to a single task (one module, one screen, one endpoint) → **single-issue mode**
   - If the description spans multiple modules, screens, or endpoints → **batch mode**
   - Batch mode heuristics: count distinct screens, API endpoints, data entities, and infrastructure tasks mentioned. Each maps roughly to 1 issue.

7) Present the analysis to the user:
   - **Single-issue mode**: Assigned issue number (e.g., ISSUE-NNN), list of docs to update with rationale for each
   - **Batch mode**: Estimated issue count (3–8 range), scope summary, list of docs to update with rationale for each, message: "This feature spans multiple areas and will be decomposed into ~N issues. Proceed?"
   - If design philosophy conflict was detected: include warning and `/uiux` suggestion
   - Wait for user confirmation before proceeding. User may: approve, modify scope, switch to single-issue mode, skip design doc updates, or abort.

### Phase 3 — Issue Creation & Doc Updates

**Single-issue mode:**

7a) Invoke the `issue-writer` agent via a single Task tool call. Include the following in the prompt:
   - The natural-language description
   - The assigned issue number
   - The list of docs to update (with rationale for each) — including design docs if applicable
   - Full content of `issues.md` (for existing issue context)
   - Full content of each planning doc marked for update
   - Full content of each design doc marked for update (if `has_design_docs` and user approved)
   - Full content of `docs/prd_digest.md` (for PRD-Ref mapping)
   - Instruction: use `flock_edit.sh` for `issues.md` and `STATUS.md`

**Batch mode:**

7b) Invoke the `planner` agent in **append mode** via a single Task tool call. Include the following in the prompt:
   - Explicit instruction: "You are operating in APPEND MODE. Read the Append Mode section of your guidelines."
   - The natural-language feature description
   - The confirmed scope (which docs to update, estimated issue count)
   - Starting issue number (max existing + 1)
   - Starting FR/NFR numbers (max existing + 1, parsed from `docs/requirements.md`)
   - Full content of `issues.md` (for existing issue context and dependency awareness)
   - Full content of each planning doc marked for update
   - Full content of each design doc marked for update (if `has_design_docs` and user approved)
   - Full content of `docs/prd_digest.md` (for PRD-Ref mapping)
   - Instruction: use `flock_edit.sh` for `issues.md` and `STATUS.md`
   - Instruction: create 3–8 issues sized 0.5d–1.5d, with dependencies, following the standard issue template
   - Instruction: update all specified docs incrementally (append-only, never modify existing entries)

### Phase 4 — Validation & Report

8) Run `python3 scripts/validate_issues.py issues.md`.
   - If violations are found: re-invoke the agent (issue-writer or planner, matching Phase 3) once with the violation list to fix them. Then re-validate.
   - If violations remain after retry: log warnings and proceed.

9) **Cross-document validation** (when design docs were updated):
   - New wireframe screens (`### Screen:` in `wireframes.md`) have matching entries in `docs/ux_spec.md`
   - New components referenced in wireframes are defined in `docs/design_system.md`
   - New screens in wireframes have copy entries in `docs/copy_guide.md`
   - New issues' PRD-Ref fields reference valid FR/NFR entries in `docs/requirements.md`
   - Log any mismatches as warnings — they do NOT block the pipeline.

10) Report to the user:

   **Single-issue mode:**
   - Issue number and title
   - List of updated docs (including design docs if applicable)
   - Validation result (pass/warnings)
   - Suggest next step: `/implement ISSUE-NNN`

   **Batch mode:**
   - List of created issues (number, title, estimate, depends-on)
   - Total estimated effort (sum of estimates)
   - List of updated docs (including design docs if applicable)
   - Cross-validation results (pass/warnings)
   - Suggest next steps:
     - `/implement ISSUE-NNN` to start with the first issue
     - `/sprint` to auto-implement all new issues
     - `/uiux` if design philosophy warning was raised or prototype needs updating

## Error Handling

- `$ARGUMENTS` is empty → ask the user for a description, stop.
- `issues.md` does not exist → instruct user to run `/kickoff` first, stop.
- All planning docs missing → update only `issues.md` + `STATUS.md`, warn the user.
- Design docs missing (`has_design_docs` is false) → skip design doc updates silently, process planning docs only.
- Design philosophy conflict detected → warn user, suggest `/uiux`, continue if user approves.
- issue-writer agent fails (single-issue mode) → retry once. If it fails again, report the error and stop.
- planner agent fails (batch mode) → retry once. If it fails again, report the error and stop.

## Rollback

- This skill is additive (appends to existing files). If partially completed, the user can manually remove the last issue block from `issues.md` and revert doc changes via git.

## Shared Registry Files
**IMPORTANT**: Never commit `issues.md`, `STATUS.md`, or `CHANGELOG.md` to the feature branch.
These are registry files managed only on main. Always use `$ROOT/` path with `flock_edit.sh`.