issue

Issue Management

Manage the issue tracking system in .issues/. This command is portable and can bootstrap issue tracking in any repository.

Usage: /issue <action> [arguments]

Actions

init

Initialize the .issues/ folder structure in a new project.

1. Create .issues/ directory
2. Create .issues/README.md with conventions documentation (template below)
3. Create empty .issues/index.md with header

README.md Template:

# Issue Tracking

This folder contains issue tracking for the repository. Each issue has its own folder with documentation.

Canonical workflow rules live in `../AGENTS.md`. Keep this file focused on `.issues/` folder conventions.

## Structure

Each `ISSUE-N/` folder contains:
- `issue.md` - Requirements and metadata (always present)
- `plan.md` - Implementation approach (created when planning)
- `session-log.md` - Append-only session progress records
- `qa-instructions.md` - Step-by-step human validation guide (created when moving to review)
- `summary.md` - Final completion record (created after verification)

## Status Values

| Status | Meaning |
|--------|---------|
| idea | Captured thought, exploration, or vague request; not yet scoped |
| backlog | Scoped but not ready to work |
| ready | Ready to work, dependencies met, acceptance criteria clear |
| in-progress | Currently being worked on |
| review | Implementation complete, awaiting verification |
| done | Verified working and accepted |

## Metadata Fields

| Field | Description |
|-------|-------------|
| Status | Current status (see above) |
| Owner | Agent / TBD / person name |
| Created | Date created (YYYY-MM-DD) |
| Source | Origin category (design-review, bug-report, etc.) |
| External | External ticket reference (optional) |
| Blocks | Issues this blocks (optional) |
| Blocked-by | Issues blocking this (optional) |
| Priority | high / medium / low |

## Commands

Use `/issue <action>` to manage issues:
- `init` - Initialize this folder structure
- `create <title>` - Create new issue
- `match <description>` - Find existing issues matching a description
- `work <id>` - Start working on an issue
- `list [status]` - Show issues
- `show <id>` - Display issue details
- `status <id> <status>` - Update status
- `plan <id>` - Create/update plan
- `session <id>` - Append session progress (run at end of each work session or before handoff)
- `done <id>` - Mark verified work complete with comprehensive summary
- `delete <id>` - Remove issue
- `index` - Regenerate index.md

## Lifecycle

1. Clarify vague requests before creating implementation-ready issues
2. Create issue with `/issue create`
3. Plan implementation, add plan.md
4. Work on issue, update status to `in-progress`
5. **After each work session or before handoff, run `/issue session` to append progress to `session-log.md`** (mandatory)
6. When implementation is complete, create `qa-instructions.md` and set status to `review`
7. After verification, run `/issue done` for final summary
8. After PR merge, run `/issue delete`

**Important:** Session log entries are mandatory for each work session or handoff point, not optional. One entry can cover multiple related edits in the same uninterrupted work session. The audit trail depends on consistent session recording.

## Session Log Template

Append each work session to `ISSUE-N/session-log.md` using this structure:

- `# Session N`
- `**Date:** YYYY-MM-DD`
- `**Prompt/Ask:**` Briefly state the user request that triggered this work.
- `## Completed`
- `## Current Status`
- `## Plan Coverage`
- `## Files Changed`
- `## Verification`
- `## Next Steps`