/improve

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:

1. **Working directory** — the repo/project the session was working in 2. **Date** — today's date 3. **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.