Issue-Craft

Produces issues that give an AI agent (or human) everything needed to implement and verify a change — without reading the entire codebase.

Prerequisites

• Context-load snapshot is complete (phase 1)
• Stack-audit findings are available (phase 2)

Issue Structure

Every crafted issue MUST have:

Title

<type>: <concise description>

Types: feat, fix, docs, refactor, chore, test, security

Labels (from label-metadata)

• Type label: bug, enhancement, documentation, refactor, chore, test, security
• Priority label: priority:P0 | priority:P1 | priority:P2 | priority:P3
• Area label: area:backend | area:frontend | area:ci | area:docs | area:security | area:devops
• Status label: ready-to-implement (if ready for autonomous work) | needs-human (if it requires a human decision) | blocked (if blocked by a dependency)
• Enhancement label (if applicable): library-review (separate lib issue) | batch-delivery (>2 AC, needs decomposition)

Type → Label Mapping

The issue title prefix maps to a type label:

Body (compressed)

## Summary
[1-2 sentences: what is broken or missing]

## Context
- Architecture: [path to architecture doc, not inline]
- Related: #[issue numbers from stack-audit, if any]

## Affected Files (best guess)
- `path/to/likely/file1`
- `path/to/likely/file2`

## Acceptance Criteria
- [ ] [Specific, verifiable behavior — reference file:function]
- [ ] [Test added in `path/to/test_file` reproducing/verifying the change]
- [ ] [N tests pass — `exact test command from context-load`]
- [ ] [CI check name passes — e.g., "test (lune)"]
- [ ] [Convention rule from AGENTS.md — e.g., "--!strict in all new files"]

## Validation
[Exact command to verify, e.g., `bash scripts/dev.sh --test`]

## Complexity
Simple | Medium | Complex
- **Simple**: 1 file, <50 lines, obvious fix
- **Medium**: 2-3 files, <200 lines, clear scope
- **Complex**: >3 files or architectural decision — consider decomposition

Acceptance Criteria Rules

1. Specific — name the file, function, or behavior exactly
2. Verifiable — can be confirmed with a test or manual step
3. Binary — pass or fail, no ambiguity
4. Contextualized — reference the project's architecture (services, controllers, signals, constants — whatever the stack uses)
5. Max 2 AC for autonomous issues — more than 2 = decompose or add batch-delivery label

AC Patterns by Issue Type

Bug Fix (fix:)

- [ ] [Behavior] no longer occurs when [reproduction steps]
- [ ] Regression test added in `[test_file]`
- [ ] [N] tests pass — `[test command]`

Feature (feat:)

- [ ] [Component] implemented in `[path]`
- [ ] Follows [convention from AGENTS.md — e.g., "--!strict"]
- [ ] Tests added in `[test_file]`
- [ ] [N] tests + new tests pass — `[test command]`
- [ ] CI check `[check name]` passes

Refactor (refactor:)

- [ ] [File:function] refactored — [measurable metric, e.g., "≤50 lines"]
- [ ] No behavior change (tests pass unchanged)
- [ ] [N] tests pass — `[test command]`

Documentation (docs:)

- [ ] Content reflects current code state
- [ ] No stale references
- [ ] No duplication with other docs (reference instead)

Library Suggestion Handling

If stack-audit found a library opportunity:

1. Create the main issue (the actual change)
2. Create a separate enhancement issue:

   ## Summary
   Evaluate [library name] for [problem it solves]
   
   ## Context
   - Could simplify: #[main issue number]
   - License: [license]
   - Bundle size: [size or "N/A"]
   - Maintenance: [active/abandoned]
   
   ## Acceptance Criteria
   - [ ] Library evaluated against project conventions
   - [ ] Trade-offs documented (license, size, deps)
   - [ ] Decision recorded (adopt/reject + reason)

3. Reference from main issue: Related: #NN (library review)

Label Validation

Before creating an issue, validate that the required labels exist in the repo:

1. Check existing labels:

   gh label list --limit 100

2. If a required label is missing, create it first (see skills/06-label-metadata/SKILL.md for the full setup commands). Do not create an issue with missing labels — gh issue create will fail.

3. Validate label assignment: every crafted issue MUST have at minimum:

   • 1 type label (bug, enhancement, documentation, refactor, chore, test, security)
   • 1 priority label (priority:P0–P3)
   • 1 area label (area:backend, area:frontend, area:ci, area:docs, area:security, area:devops)

   If any of these three categories is missing, add needs-metadata label and flag the issue for review.

Launch

gh issue create \
  --title "fix: flashlight uses :Fire() instead of :FireServer()" \
  --body-file /tmp/issue-body.md \
  --label "bug" \
  --label "priority:P0" \
  --label "area:backend" \
  --label "ready-to-implement"

Record the issue number in the progress file.

Error Handling

• gh CLI not installed: issue-craft cannot create issues without gh. Report "gh CLI not found — issue body saved to /tmp/issue-body.md. Install gh to create: https://cli.github.com/" and save the draft for manual creation.
• gh not authenticated: run gh auth status. If not authed, report "gh not authenticated — run gh auth login and retry." Save the draft.
• GitHub API rate limits: if gh issue create fails with a rate limit error, save the draft and report "Rate limited — retry after [reset time]. Issue body at /tmp/issue-body.md."
• Labels don't exist: see Label Validation above. Create missing labels before retrying gh issue create.
• Commands fail: if gh issue create fails for any other reason (network, permissions), save the draft and report the error. Do not lose the crafted issue body.

Example

Complete crafted issue for a bug fix:

Title: fix: flashlight uses :Fire() instead of :FireServer()

Labels: bug, priority:P0, area:backend, ready-to-implement

## Summary
The flashlight tool calls `:Fire()` on the client, which does not replicate
to the server. It should use `:FireServer()` so the server authorizes the
action.

## Context
- Architecture: docs/ARCHITECTURE.md §Tools
- Related: #12 (orphan PR with same fix attempt)

## Affected Files (best guess)
- src/client/Controllers/ToolController.luau
- src/server/Services/ToolService.luau

## Acceptance Criteria
- [ ] `ToolController:activateTool()` calls `:FireServer()` instead of `:Fire()`
- [ ] Regression test added in `scripts/test_tools.luau`
- [ ] 26 tests pass — `lune run scripts/test_core.luau`

## Validation
`lune run scripts/test_core.luau`

## Complexity
Simple — 1 file, <20 lines, obvious fix