gh-ticket

What this skill does

# GitHub Ticket (Create or Update)

## Why This Skill Exists

**The moment you decide to create a ticket, you have MAXIMUM CONTEXT.**

- You just investigated the problem
- You understand the codebase state
- You know the requirements
- You have the error messages fresh
- You understand the dependencies

**If you don't capture this NOW, it's lost forever.** The implementer (even if it's you later) will have to re-discover everything.

## The Cost of Vague Tickets

| Vague Ticket | Cost |
|--------------|------|
| "Fix auth bug" | Implementer spends 2 hours finding which bug |
| "Add user settings" | 5 back-and-forth clarifications |
| "Improve performance" | Implementation doesn't match intent |
| "Handle edge case" | Which edge case? What behavior? |

**Every minute spent writing a good ticket saves 10 minutes of implementation confusion.**

---

## When to Use This Skill

- **Creating** a new GitHub issue
- **Updating** an existing issue with new context/requirements
- **Expanding** a vague issue into a comprehensive spec
- **Adding** implementation details discovered during investigation

---

## Ticket Process (Create or Update)

### Phase 1: Context Capture (DO THIS FIRST)

Before writing anything, gather ALL available context:

#### Step 1: Dump Current Context

Ask yourself and document:

```markdown
## Context Dump (will be refined)

### What triggered this?
- [User request? Bug report? Code review finding? Your own observation?]

### What do I know right now?
- [Everything in your head about this issue]

### What files are involved?
- [List every file you've looked at or that's relevant]

### What did I discover?
- [Findings from investigation, errors seen, behavior observed]

### What's the current state?
- [How does it work now? What's broken?]

### What should the end state be?
- [Desired behavior, expected outcome]
```

#### Step 2: Gather Technical Evidence

```bash
# If there's an error, capture it
# If there are relevant files, note their paths
# If there's relevant git history, capture it
git log --oneline -10 -- path/to/relevant/file

# If there's related code, note the exact locations
grep -n "relevant_function" src/**/*.ts
```

#### Step 3: Check for Related Context

```bash
# Related issues?
gh issue list --search "related keywords"

# Related PRs?
gh pr list --search "related keywords"

# Any existing documentation?
find . -name "*.md" | xargs grep -l "related topic"
```

---

### Phase 2: Requirements Extraction

**CRITICAL**: Extract EVERY requirement as a checkbox item.

#### Functional Requirements

What must the implementation DO?

```markdown
## Requirements

### Functional
- [ ] [Specific action/behavior 1]
- [ ] [Specific action/behavior 2]
- [ ] [Specific action/behavior 3]
```

**Rules for writing requirements:**
- Start with a verb (Create, Add, Update, Remove, Fix, Handle)
- Be specific (not "handle errors" but "return 400 with validation message when email invalid")
- One requirement per checkbox
- If it's complex, break it down

#### Edge Cases

What edge cases must be handled?

```markdown
### Edge Cases
- [ ] Handle empty input: [expected behavior]
- [ ] Handle null/undefined: [expected behavior]
- [ ] Handle network failure: [expected behavior]
- [ ] Handle concurrent access: [expected behavior]
```

#### Acceptance Criteria

How do we KNOW it's done?

```markdown
### Acceptance Criteria
- [ ] [Specific testable criterion 1]
- [ ] [Specific testable criterion 2]
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] No TypeScript errors
- [ ] Linting passes
```

---

### Phase 3: Implementation Guidance

Give the implementer a head start with everything you know.

#### Affected Files

```markdown
## Implementation Notes

### Files to Modify
- `src/services/auth.ts` - Add token refresh logic
- `src/api/handlers/login.ts` - Update error responses
- `src/types/auth.ts` - Add new type for refresh token

### Files to Create
- `src/services/token-refresh.ts` - New service for refresh logic

### Files to Delete
- `src/utils/old-auth-helper.ts` - Replaced by new service
```

#### Relevant Code Locations

```markdown
### Key Code Locations

**Entry point**: `src/api/handlers/login.ts:45` - `handleLogin()`
**Token generation**: `src/services/auth.ts:120` - `generateToken()`
**Related type**: `src/types/auth.ts:15` - `AuthToken`

**Similar pattern exists in**: `src/services/session.ts:80` - follow this pattern
```

#### Dependencies & Blockers

```markdown
### Dependencies
- Depends on: #123 (database migration must be done first)
- Blocks: #456 (this must be done before that can start)
- Related to: #789 (similar work, coordinate)

### Blockers
- [ ] Waiting on API spec from backend team
- [ ] Need design mockup for UI
```

---

### Phase 4: Ticket Structure Template

Use this exact structure for every ticket:

```markdown
## Summary

[1-2 sentence description of what this ticket accomplishes]

## Context

### Background
[Why does this need to happen? What triggered this?]

### Current State
[How does it work now? What's the problem?]

### Desired State
[How should it work after implementation?]

## Requirements

### Functional Requirements
- [ ] [Requirement 1 - specific, actionable]
- [ ] [Requirement 2 - specific, actionable]
- [ ] [Requirement 3 - specific, actionable]

### Edge Cases
- [ ] [Edge case 1]: [expected behavior]
- [ ] [Edge case 2]: [expected behavior]

### Acceptance Criteria
- [ ] [Criterion 1 - testable]
- [ ] [Criterion 2 - testable]
- [ ] All tests pass
- [ ] No TypeScript errors
- [ ] Code review approved

## Implementation Notes

### Files to Modify
- `path/to/file1.ts` - [what changes]
- `path/to/file2.ts` - [what changes]

### Files to Create
- `path/to/new-file.ts` - [purpose]

### Files to Delete
- `path/to/old-file.ts` - [why removing]

### Key Code Locations
- `file.ts:line` - [relevant function/class]
- `file.ts:line` - [related code to reference]

### Suggested Approach
[If you have ideas on HOW to implement, share them]

### Similar Patterns
[Point to existing code that solves similar problems]

## Dependencies

- Depends on: [#issue or description]
- Blocks: [#issue or description]
- Related: [#issue or description]

## Out of Scope

[Explicitly list what this ticket does NOT cover to prevent scope creep]

- Not doing X (that's #456)
- Not changing Y (separate ticket needed)

## Technical Notes

[Any technical context that helps: error messages, stack traces, config values, environment details]

```

---

### Phase 5: Create or Update the Ticket

#### Creating a New Issue

```bash
# Create with full body using heredoc
gh issue create --title "[Type]: Brief description" --body "$(cat <<'EOF'
[Full ticket body here using template above]
EOF
)"

# Or create from file
echo "[ticket content]" > /tmp/ticket.md
gh issue create --title "[Type]: Brief description" --body-file /tmp/ticket.md

# Add labels
gh issue edit <number> --add-label "type:feature,priority:high"
```

#### Updating an Existing Issue

```bash
# View current issue content
gh issue view <number>

# Update issue body (replaces entire body)
gh issue edit <number> --body "$(cat <<'EOF'
[Updated full ticket body]
EOF
)"

# Update just the title
gh issue edit <number> --title "[Type]: Updated description"

# Add a comment with new context (preserves original body)
gh issue comment <number> --body "$(cat <<'EOF'
## Additional Context Discovered

[New findings, updated requirements, implementation notes]
EOF
)"

# Add labels
gh issue edit <number> --add-label "type:feature,priority:high"
```

#### When to Update vs Comment

| Situation | Action |
|-----------|--------|
| Issue was vague, now have full spec | **Update body** - replace with complete spec |
| Found new requirements during investigation | **Update body** - add to requirements section |
| Progress update or status change | **Comment** - preserve history |
| Minor clarification | **Comment** - don't rewrite whole issue |
| Issue scope changed significantly | **Update bod