Kit Preamble — 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

Kit Preamble — issue

Kit Update Check

Run silently at the start:

python3 scripts/kit_update_check.py 2>/dev/null

If exit code is 1 (update available), show the output to the user once. Do not block the workflow.

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.

Behavioral Rules

• Verify gh auth status before any GitHub operation.
• Never commit secrets, API keys, or credentials. Use environment variables.
• Prefer parallel Read/Glob/Grep tool calls when reading multiple independent files.
• When uncertain about intent, ask the user rather than guessing.
• Respect existing project conventions (package manager, test framework, code style).

Contributor Mode

At the start of this skill, check if contributor mode is enabled:

python3 scripts/kit_config.py get contributor_mode

If the result is true:

1. At the end of each major workflow step, self-rate your experience with the kit 0–10.
2. If rating < 10 and there is an actionable improvement, file a field report:

   python3 scripts/contributor_report.py --skill <name> --step "<step>" --rating <N> --notes "<friction or suggestion>"
   

3. Maximum 3 reports per session. Skip if a report for the same step already exists.
4. Do NOT stop the workflow to file reports — do it inline.
5. Only report kit/skill issues (unclear instructions, missing checkpoints, bad ergonomics). Do NOT report user-app bugs or network errors.

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.