github-issue

# GitHub Issue Management Skill

This skill provides a structured approach to writing GitHub issues that communicate context, scope, and direction clearly.

## Title Format (Required)

Issue titles **must** follow conventional commit format:

```
<type>(<scope>): <description>
```

**Valid types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`

**Examples:**
- `feat(auth): add OAuth2 login support`
- `fix(api): resolve race condition in request handler`
- `chore(deps): update dependencies to latest versions`
- `docs(readme): add installation instructions`

The script validates this format automatically. Use `--skip-validation` only if the repository uses a different convention.

---

## The Why/What/How Framework

Every issue should answer three questions for the reader:
- **Why** does this matter?
- **What** exactly needs to happen?
- **How** should it be approached?

This framework ensures issues are actionable and provide enough context for anyone picking them up.

---

## Issue Template

### Why

Explain the background and motivation:

- **Current state**: What exists today? How does it work?
- **Bottleneck/Problem**: What specific issue or limitation was identified?
- **Value**: Why is solving this valuable? What insights, metrics, or improvements does it unlock?

```markdown
## Why

Currently, [describe current state/behavior].

This causes [specific problem or bottleneck], which [impact on users/system/workflow].

Addressing this will [concrete benefit - improved metrics, unlocked capabilities, better UX].
```

### What

Define the scope concretely:

- **Specific deliverable**: What exactly needs to be built, fixed, or changed?
- **Boundaries**: What is explicitly out of scope?
- **Success criteria**: How do we know when this is done?

```markdown
## What

[Verb] [specific thing] to [achieve outcome].

Scope:
- [In scope item 1]
- [In scope item 2]

Out of scope:
- [Explicitly excluded item]
```

### How

Provide