vm-github-issue-writer

# VM GitHub Issue Writer

Create GitHub issues that are ready to hand to engineering without forcing the assignee to reverse-engineer intent.

## When To Use

Use this skill when the user wants to:

- Turn rough work into a GitHub issue
- Convert requirements, PRDs, BRDs, architecture notes, or meeting notes into an implementation ticket
- Create a story or engineering requirement with explicit acceptance criteria
- Tighten an underspecified issue before it is filed

Do not use this skill for:

- Pull request descriptions
- Incident tickets or postmortems
- Full PRDs or architecture documents

## Required Outcome

Produce these two outputs:

1. A concise GitHub issue title
2. A markdown issue body using the template in [github-issue-template.md](./assets/github-issue-template.md)

If the input is missing critical information, produce the best issue you can without inventing facts and add the gaps to `Open Questions`.

## Decision Logic

### 1. Choose the issue framing

- Use **User Story** framing when the work is user-centric and the value is best expressed as "As a..., I want..., so that..."
- Use **Requirement** framing when the work is system-centric, platform-centric, integration-centric, operational, security, or infrastructure-focused
- Use **Bug Fix** framing only if the user clearly describes broken current behavior
- If the framing is ambiguous, default to **Requirement** and state the ambiguity in `Open Questions`

### 2. Extract the minimum issue inputs

Capture, in this order:

- The problem or opportunity
- The desired outcome or value
- The scope of work
- Constraints, assumptions, or non-goals
- Dependencies and impacted systems
- Evidence or source references
- Acceptance criteria that can be verified

### 3. Normalize weak inputs

- Rewrite vague requests into specific implementation intent
- Split business value from implementation notes
- Convert implicit success conditions into explicit acceptance criteria
- Move speculative items into `Open Questions` or `Risks / Constraints`
- Keep the issue self-contained enough that an engineer can start work without reopening discovery from scratch

## Title Rules

Write the title as a short action-oriented statement.

- Prefer verb-first phrasing
- Keep it under 80 characters when practical
- Avoid filler such as "Need to", "Work on", or "Investigate" unless the work is genuinely exploratory
- Do not include markdown headings or ticket IDs in the title

Examples:

- `Add health check endpoint for outage reporter service`
- `Harden prompt logging to avoid sensitive customer data exposure`
- `Fix duplicate event emission during outage status updates`

## Body Construction Rules

Always use the exact section order from [github-issue-template.md](./assets/github-issue-template.md).

### Summary

- Explain the work in 2-4 sentences
- State the business or operational reason the work matters

### Work Type

- Set one of: `User Story`, `Requirement`, `Bug Fix`, `chore`, `Spike`

### Problem