create-issue

Skill: Create a GitHub Issue

When to use

When you need to file a new issue — whether from discovering a bug, scoping a feature, splitting work from an epic, or deferring feedback from a code review.

Issue quality bar

Every issue must be shovel-ready: an agent or developer should be able to pick it up and start implementing without asking clarifying questions.

Steps

1. Choose the title format

2. Write the issue body

Use this structure (omit sections that don't apply):

## Summary

One paragraph: what this issue is about and why it matters.

**Parent**: <Epic name> (if this is a sub-issue)
**Depends on**: #N (if there are blocking dependencies)
**Origin**: <PR link or review comment> (if deferred from a review)

## Problem / Background

What's broken or missing? Be specific:
- Current behavior (with code references: `file.rs:line`)
- Expected behavior
- User impact

## Proposed Solution / Fix

What should be done? Include:
- Code changes with snippets showing the approach
- Which pattern to follow (reference existing code)
- Alternatives considered and why they were rejected

## Files to Modify

| File | Change |
|------|--------|
| `src/ui/app.rs` | Add match arm for new action |
| `src/ui/buffers/help.rs` | Update help text |

## Acceptance Criteria

- [ ] Criterion 1 (specific, testable)
- [ ] Criterion 2
- [ ] All existing tests pass (`cargo test`)
- [ ] `cargo clippy -- -D warnings` passes
- [ ] `cargo fmt --check` passes

## Testing Strategy

### Unit Tests
- What to test and expected behavior

### Integration Tests
- End-to-end workflows to verify

### Manual Tests
- Steps to manually verify (for UI changes)

## Implementation Notes

Non-obvious technical details, gotchas, or constraints.

## Definition of Done

- [ ] Functionality implemented according to requirements
- [ ] Unit tests written and passing
- [ ] Code passes linting (clippy) with no warnings
- [ ] Code formatted with rustfmt
- [ ] Documentation updated (if applicable)

3. Calibrate detail level by effort

4. Reference real code

Always verify before writing:

• Check src/ui/keybindings.rs for keybinding claims
• Check src/ui/app.rs for command dispatch
• Check src/config.rs for config field names
• Check src/constants.rs for threshold values
• Include approximate line numbers (e.g., app.rs:~1212)

5. Link to context

• Sub-issue of an epic? Add **Parent**: <Epic title> in summary
• Deferred from a review? Add **Origin**: <PR link> with the review comment URL
• Depends on another issue? Add **Depends on**: #N
• Related to prior work? Add **Related**: #N, PR #M

6. Create the issue

Always use a PowerShell here-string for the body — backtick is PowerShell's escape character and any backtick-quoted code in markdown will corrupt or crash if passed as an inline string literal.

# Single-quoted here-string: backticks, $vars, and quotes are all literal.
# The closing '@ MUST be at column 0 (no leading spaces).
$body = @'
## Summary

<paste your drafted body here>
'@

gh issue create --title "[Feature] Your title" --body $body

7. Apply labels

Use the triage-issue skill to apply the correct labels after creation.

Anti-patterns

• ❌ Vague acceptance criteria: "It should work correctly" → be specific
• ❌ Missing code references: "Fix the sync buffer" → say which file, which function, which line
• ❌ No testing guidance: Always include what to test and how
• ❌ Scope creep: One issue = one logical unit of work. If it's multiple things, split into sub-issues
• ❌ Implementation-free: Don't just describe the problem — sketch the solution with code snippets

Examples of well-written issues in this repo

• XS/S: Issue #64 — concise, 5 specific changes, clear before/after
• M: Issue #48 — two options with code, constraints, compatibility notes
• L: Issue #74 — root cause analysis, fix per root cause, line references
• Epic: Issue #73 — phased breakdown, keybinding table, design decisions