Shape issues

Raw ideas become well-scoped issues the resolver can act on. The /shape-issues skill applies Shape Up methodology to GitHub issues before they hit the pipeline.

Rough idea in. Clear problem statement, appetite, scope boundaries, and acceptance criteria out.

/shape-issues is a local Claude Code skill that takes raw issue text — a one-line note, a Slack quote, a brain dump — and reshapes it into a structured GitHub issue. The reshaped issue carries enough scope clarity that issue-resolver.yml in ai-workflows can draft a sensible PR against it, instead of stalling on ambiguity.

Why shaping matters

issue-resolver.yml is conservative by design. It refuses to draft PRs for issues labeled type:security, type:feature, type:breaking, or size:l/xl — the situations where AI judgment carries too much risk. Issues that aren’t labeled at all default to “don’t act.”

That means the difference between an issue that gets a PR and one that sits is often how the issue is written, not how clever the AI is. A vague “improve docs structure” stays untouched. A well-shaped “add a Comparison table to infrastructure/lxc-vs-docker.mdx with columns Memory / Disk / Network / Startup time, fed from the Proxmox cluster benchmark notes” gets a draft PR in five minutes.

What Shape Up gives you

Shape Up is Basecamp’s product-shaping methodology. The relevant elements for /shape-issues:

Concept	What it means here
Problem	One sentence — the real thing that needs solving, not the symptom
Appetite	How much time/risk this is worth (1 day, 1 week, 6 weeks) — gates whether the issue should even be opened
Solution sketch	A 2–4 bullet outline of the approach — enough that a reasonable agent can act, vague enough to leave room for judgment
Rabbit holes	Things the implementer might fall into and burn time on — explicitly out of scope
No-goes	What this issue will not address (so a follow-up issue can hold those instead)

What the skill outputs

/shape-issues rewrites a draft issue body into this shape:

## Problem
One sentence stating the actual pain or gap.

## Appetite
1 day | 1 week | 6 weeks

## Solution sketch
- Bullet 1: the highest-leverage change
- Bullet 2: the supporting change
- Bullet 3: validation step

## Rabbit holes
- Thing you'll be tempted to rewrite, but don't
- Adjacent system that's broken but out of scope

## No-goes
- Explicit non-goals

Plus a recommended label set (size:s, type:enhancement, etc.) based on appetite + scope.

How /shape-issues connects to the pipeline

Raw idea
   ↓
/shape-issues (local)
   ↓
gh issue create
   ↓
ai-workflows/issue-triage.yml      ← applies labels
ai-workflows/issue-resolver.yml    ← drafts a PR (or skips with reason)
   ↓
Cloud pipeline takes over from here

The skill itself doesn’t open the issue — you review the shaped output, then gh issue create --title ... --body .... The triage workflow takes over once GitHub fires the issues: [opened] event.

When NOT to use /shape-issues

• Bug reports with a clear reproduction. A trace and a stack speak for themselves; shaping adds noise.
• One-line typo fixes. Just open the issue.
• Anything with type:security label. Security issues are handled outside the resolver pipeline; shape them differently.
• Major architectural decisions. Those need an RFC or a design doc, not an issue.

Where to go next

ai-workflows / issue-resolver

The downstream consumer — what /shape-issues is preparing input for.

Issue → PR pipeline

What happens after a shaped issue is opened.

Shape Up book

The full methodology Basecamp open-sourced.

claude-code-plugins

The plugin home for /shape-issues.