# Shape Issues

> Shape raw ideas into actionable GitHub Issues using Shape Up methodology Use when this capability is needed.

- Skill: `tomevault-io/shape-issues` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/shape-issues`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/shape-issues/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/shape-issues

---


# Shape Issues

Iterative issue exploration and shaping process that transforms rough ideas into well-defined,
time-boxed GitHub Issues using Shape Up methodology and continuous discovery principles.

> **Attribution**: Based on work by [roksechs](https://gist.github.com/roksechs/3f24797d4b4e7519e18b7835c6d8a2d3)

## Phases

1. **Problem Exploration**: Examine raw ideas, map pain points, assess timebox
2. **Solution Sketching**: Brainstorm approaches, set scope boundaries, identify risks
3. **Issue Formation**: Problem statement, timebox, solution sketch, rabbit holes
4. **Betting Table**: Prioritize by timebox, balance portfolio, set circuit breakers
5. **Issue Crafting**: Create GitHub Issues with size labels, handoff to `/resolve-issues`

## Sizing

| Label | Duration |
| --- | --- |
| `size:xs` | < 1 day |
| `size:s` | 1-3 days |
| `size:m` | 3-5 days |
| `size:l` | 1-2 weeks |
| `size:xl` | 2+ weeks |

## Workflow

1. Gather context: `gh issue list`, `gh pr list`
2. Explore problem: user complaints, workflow friction, timebox check
3. Sketch solutions: 2-3 approaches, scope boundaries, rabbit holes
4. Set timebox: spike vs small batch vs big batch
5. Create issue: `gh issue create` with template, add `ready-for-dev` label

## Issue Template

Key sections: Problem (raw idea, pain, size), Solution Sketch (concept, out of scope),
Rabbit Holes (complexity traps), Done Looks Like (acceptance criteria).

## Usage

```text
/shape-issues
```

**Workflow**: `/shape-issues` -> `/resolve-issues` -> `/review-pr` -> `/resolve-pr-review-thread`

## Related Skills

- pr-standards (git-standards) — PR authoring and review standards applied after issues are implemented

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/jacobpevans) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->