refine-issue skill
Fetch a GitHub issue by number and rewrite it to a consistent template. The skill reads the issue, optionally reads the codebase for context, then produces a structured version with a gitmoji-prefixed title, 🎯 Problem, 📋 Description, ✅ Acceptance Criteria, and more. Shows a before/after diff before updating.
features
- fetches issue title, body, and labels via
gh issue view --json
- reads codebase (
git ls-files + key files) to enrich Technical Notes and validate acceptance criteria
- rewrites to the same template used by
/create-issue: gitmoji title, 🎯 Problem, 📋 Description, ✅ Acceptance Criteria, 🔁 Steps to Reproduce (bugs), 💡 Technical Notes
- preserves any good content already in the issue — rewrites structure, not ideas
- proposes an improved title only when the existing one is too vague (e.g., "fix bug", "update")
- shows a before/after diff and waits for confirmation before posting
--dry-run prints the gh issue edit command without executing it- updates in-place via
gh issue edit
usage
/refine-issue <number> # fetch, rewrite, confirm, update
/refine-issue <number> --repo owner/repo
/refine-issue <number> --dry-run # show rewritten issue without posting
gitmoji reference
| Type |
Gitmoji |
Example title |
| feat |
✨ |
✨ add oauth login via google |
| bug |
🐛 |
🐛 password reset link expires too early |
| chore |
🔧 |
🔧 upgrade go to 1.23 |
| refactor |
♻️ |
♻️ simplify auth middleware |
| perf |
⚡️ |
⚡️ cache user profile queries |
| docs |
📝 |
📝 document deployment steps |
| test |
🧪 |
🧪 add integration tests for login flow |
| security |
🔒 |
🔒 sanitize file upload paths |
| ui |
💄 |
💄 update button styles to match design system |
issue template
## 🎯 Problem
<one paragraph — why this matters, what pain it addresses>
## 📋 Description
<what needs to be done>
## ✅ Acceptance Criteria
- [ ] <criterion 1>
- [ ] <criterion 2>
## 🔁 Steps to Reproduce
> Only included for bug issues
1. <step 1>
2. <step 2>
- **Expected:** <what should happen>
- **Actual:** <what happens instead>
## 💡 Technical Notes
> Optional — file paths, APIs, related code, implementation hints
workflow
parse args: require <number>; extract --repo, --dry-run
- if no number is given: ask "Which issue number would you like to refine?"
fetch issue:
gh issue view <number> --json title,body,labels,state [--repo owner/repo]
- if not found: surface the full
gh error and stop
read codebase context:
- run
git ls-files to see the file structure
- read README and 1–2 files most likely touched by this issue (infer from title/body keywords)
- use this context to fill gaps in Technical Notes and check acceptance criteria against reality
analyze existing content:
- detect issue type from labels and body keywords (same rules as
/create-issue)
- map existing prose to template sections — preserve any good content
- identify gaps: missing acceptance criteria, vague problem statement, missing repro steps for bugs
- flag titles that are too vague (single word, "fix bug", "update X") → propose improvement
rewrite:
- produce a full template-conformant body with all sections filled
- prefix title with correct gitmoji (keep original title text if good; improve if vague)
- omit 🔁 Steps to Reproduce for non-bug issues
- omit 💡 Technical Notes if no useful content exists
show diff: print old title + body, then new title + body, and ask:
Update issue #<n> with this rewrite? [yes / edit / cancel]
- edit: ask what to change, regenerate, show diff again
- cancel: stop — issue is unchanged
- yes: proceed
post:
gh issue edit <number> \
--title "<gitmoji> <title>" \
--body "<body>" \
[--repo <owner/repo>]
- if
--dry-run: print the command above without running it
report: print the issue URL
best practices
- never update without confirmation — always show the diff and wait; never call
gh issue edit without user approval
- preserve the author's intent — reformat structure but keep their words and domain knowledge; don't paraphrase away meaning
- acceptance criteria are checkboxes — always convert plain bullet lists to
- [ ] task items
- steps to reproduce are for bugs only — omit the section entirely for non-bug issues
- title gitmoji reflects type, not sentiment — pick from the fixed mapping; don't invent new emoji for titles
- codebase reads are lightweight —
git ls-files + 1–2 files max; this is context, not a full code review
- only improve vague titles — if the existing title is specific and accurate, keep it (minus the gitmoji prefix); don't rewrite good titles
1---2name: refine-issue3description: Fetches an existing GitHub issue by number, rewrites it to a structured template with gitmoji title and consistent sections (problem, acceptance criteria, steps to reproduce, technical notes), and updates it in-place via gh issue edit.4---56# refine-issue skill78Fetch a GitHub issue by number and rewrite it to a consistent template. The skill reads the issue, optionally reads the codebase for context, then produces a structured version with a gitmoji-prefixed title, 🎯 Problem, 📋 Description, ✅ Acceptance Criteria, and more. Shows a before/after diff before updating.910## features1112- fetches issue title, body, and labels via `gh issue view --json`13- reads codebase (`git ls-files` + key files) to enrich Technical Notes and validate acceptance criteria14- rewrites to the same template used by `/create-issue`: gitmoji title, 🎯 Problem, 📋 Description, ✅ Acceptance Criteria, 🔁 Steps to Reproduce (bugs), 💡 Technical Notes15- preserves any good content already in the issue — rewrites structure, not ideas16- proposes an improved title only when the existing one is too vague (e.g., "fix bug", "update")17- shows a before/after diff and waits for confirmation before posting18- `--dry-run` prints the `gh issue edit` command without executing it19- updates in-place via `gh issue edit`2021## usage2223```24/refine-issue <number> # fetch, rewrite, confirm, update25/refine-issue <number> --repo owner/repo26/refine-issue <number> --dry-run # show rewritten issue without posting27```2829## gitmoji reference3031| Type | Gitmoji | Example title |32|------|---------|---------------|33| feat | ✨ | `✨ add oauth login via google` |34| bug | 🐛 | `🐛 password reset link expires too early` |35| chore | 🔧 | `🔧 upgrade go to 1.23` |36| refactor | ♻️ | `♻️ simplify auth middleware` |37| perf | ⚡️ | `⚡️ cache user profile queries` |38| docs | 📝 | `📝 document deployment steps` |39| test | 🧪 | `🧪 add integration tests for login flow` |40| security | 🔒 | `🔒 sanitize file upload paths` |41| ui | 💄 | `💄 update button styles to match design system` |4243## issue template4445```markdown46## 🎯 Problem4748<one paragraph — why this matters, what pain it addresses>4950## 📋 Description5152<what needs to be done>5354## ✅ Acceptance Criteria5556- [ ] <criterion 1>57- [ ] <criterion 2>5859## 🔁 Steps to Reproduce6061> Only included for bug issues62631. <step 1>642. <step 2>65- **Expected:** <what should happen>66- **Actual:** <what happens instead>6768## 💡 Technical Notes6970> Optional — file paths, APIs, related code, implementation hints71```7273## workflow74751. **parse args**: require `<number>`; extract `--repo`, `--dry-run`76 - if no number is given: ask "Which issue number would you like to refine?"77782. **fetch issue**:79 ```bash80 gh issue view <number> --json title,body,labels,state [--repo owner/repo]81 ```82 - if not found: surface the full `gh` error and stop83843. **read codebase context**:85 - run `git ls-files` to see the file structure86 - read README and 1–2 files most likely touched by this issue (infer from title/body keywords)87 - use this context to fill gaps in Technical Notes and check acceptance criteria against reality88894. **analyze existing content**:90 - detect issue type from labels and body keywords (same rules as `/create-issue`)91 - map existing prose to template sections — preserve any good content92 - identify gaps: missing acceptance criteria, vague problem statement, missing repro steps for bugs93 - flag titles that are too vague (single word, "fix bug", "update X") → propose improvement94955. **rewrite**:96 - produce a full template-conformant body with all sections filled97 - prefix title with correct gitmoji (keep original title text if good; improve if vague)98 - omit 🔁 Steps to Reproduce for non-bug issues99 - omit 💡 Technical Notes if no useful content exists1001016. **show diff**: print old title + body, then new title + body, and ask:102 `Update issue #<n> with this rewrite? [yes / edit / cancel]`103 - **edit**: ask what to change, regenerate, show diff again104 - **cancel**: stop — issue is unchanged105 - **yes**: proceed1061077. **post**:108 ```bash109 gh issue edit <number> \110 --title "<gitmoji> <title>" \111 --body "<body>" \112 [--repo <owner/repo>]113 ```114 - if `--dry-run`: print the command above without running it1151168. **report**: print the issue URL117118## best practices119120- **never update without confirmation** — always show the diff and wait; never call `gh issue edit` without user approval121- **preserve the author's intent** — reformat structure but keep their words and domain knowledge; don't paraphrase away meaning122- **acceptance criteria are checkboxes** — always convert plain bullet lists to `- [ ]` task items123- **steps to reproduce are for bugs only** — omit the section entirely for non-bug issues124- **title gitmoji reflects type, not sentiment** — pick from the fixed mapping; don't invent new emoji for titles125- **codebase reads are lightweight** — `git ls-files` + 1–2 files max; this is context, not a full code review126- **only improve vague titles** — if the existing title is specific and accurate, keep it (minus the gitmoji prefix); don't rewrite good titles
pavelsimo