| name | improve |
| description | Create a structured GitHub issue from a session reflection or improvement idea using the gh CLI. Use this skill when the user asks to create an issue from a reflection, file an improvement, log a lesson learned, or says things like "make an issue for that", "track this", "file that as a bug", "create an improvement issue", or after running /reflect when the user agrees to capture findings. Also use when the user identifies something that should be fixed or improved and wants it tracked in GitHub.
|
Improve
Turn session insights into a trackable GitHub issue. This skill bridges the gap
between "we noticed a problem" and "someone will fix it" — every issue it creates
links back to where the idea came from so future readers have full context.
Step 1: Gather the improvement
Check the current conversation for a /reflect retrospective or other discussion
about what to improve. If there's a clear reflection with pain points, use that.
If there's no reflection in the conversation, ask the user what they'd like to
improve. A single sentence is enough to get started.
If a /reflect produced multiple pain points, ask the user which ones to turn
into issues (they may want one issue, several, or all of them).
Step 2: Build the origin reference
Every issue must trace back to its origin so future readers understand the context.
Collect these details:
- Working directory — the repo/project the session was working in
- Date — today's date
- Trigger — what specifically surfaced this (e.g., "reflection after refactoring the fetcher pipeline" or "user noticed flaky test during PR review")
Step 3: Structure the issue
Draft the issue with this structure:
## Problem
What went wrong or what could be better. Be specific — name the files, tools,
or workflows involved.
## Context
Why this matters. What was the user trying to do when this came up.
## Suggested improvement
Concrete next steps. What should change and roughly how.
## Origin
- **Date:** <date>
- **Working directory:** `<path>`
- **Trigger:** <what surfaced this>
Write a concise title (under 70 characters) that captures the improvement, not
the session. Good: "Add retry logic to RSS fetcher timeout handling". Bad:
"Session reflection issue".
Step 4: Confirm with the user
Show the draft title and body. Ask for confirmation before creating. The user
might want to adjust scope, wording, or labels.
Step 5: Create the issue
Use the gh CLI to create the issue in the current repository:
gh issue create --title "<title>" --body "<body>"
Use a HEREDOC for the body to preserve formatting:
gh issue create --title "the title" --body "$(cat <<'EOF'
issue body here
EOF
)"
If the user wants labels, add --label "label1,label2". Common useful labels:
improvement, dx, bug, documentation.
Report the issue URL back to the user when done.
