Issue Decomposition Skill Skill

Issue Decomposition Skill

Transform high-level project descriptions into well-structured GitHub issues. Each issue includes a user story, acceptance criteria, dependencies, labels, and a story-point estimate on the powers-of-two scale from the estimating-work-items skill.

When to Use

Activate this skill when:

User describes a feature or project to break down
User says "create issues for...", "break this into tasks", "decompose this feature"
During project planning to generate actionable work items
When converting requirements into GitHub issues

When NOT to use: not for single bug reports or tasks already small enough to be one issue; not for dependency visualization (use the dependency-mapping skill).

Issue Template

Each generated issue follows this structure:

# [Concise, Action-Oriented Title]

## User Story
As a [persona/role], I want [goal/action] so that [benefit/value].

## Description
[2-4 sentences explaining the context and what needs to be done]

## Acceptance Criteria
- [ ] Criterion 1: Specific, testable requirement
- [ ] Criterion 2: Another measurable outcome
- [ ] Criterion 3: Edge case or validation requirement

## Dependencies
- Blocked by: #[number] - [brief reason]
- Blocks: #[number] - [what depends on this]

## Labels
`[type]`, `[area]`, `[priority]`, `points-[n]`

## Estimate
**[n] points**

Compared with: [smaller reference] ([n]) and [larger reference] ([n]) - [why it is closer to one than the other].
Main unknown: [the one thing most likely to make this bigger], or "none".
Estimated by: [model] in [harness], estimating-work-items [version]

Decomposition Process

Step 1: Understand the Scope

Ask clarifying questions if needed:

What is the core goal of this project/feature?
Who are the primary users?
Are there any technical constraints or preferences?
What's the target timeline?

Step 2: Identify Major Components

Break the project into 3-7 major areas:

Foundation/Setup tasks
Core functionality
Supporting features
Integration points
Testing/Validation

Step 3: Generate Issues

For each component, create issues that are:

Independent: Minimal dependencies on other issues
Negotiable: Clear what, flexible how
Valuable: Delivers user or technical value
Estimable: Passes the estimability gate in estimating-work-items (you can say what done looks like)
Small: 8 points or less on the powers-of-two scale; anything bigger is an epic with its own children
Testable: Has clear acceptance criteria

Step 4: Map Dependencies

Identify blocking relationships:

Sequential dependencies (A must finish before B)
Parallel opportunities (can be done simultaneously)
Critical path (longest chain of dependent issues)

Step 5: Preview Before Creating

Always show the user a summary before creating issues:

## Proposed Issues (N total)

| # | Title | Points | Dependencies |
|---|-------|--------|--------------|
| 1 | Setup project structure | 2 | None |
| 2 | Implement core feature X | 4 | Blocked by #1 |
...

Proceed with creation? (y/n)

Step 6: Create the Issues

On approval, create each issue with gh issue create --title ... --body ... --label ... (requires the gh CLI authenticated for the repo). If gh is unavailable, output the issue bodies for manual creation.

Label Taxonomy

Check existing repo labels first (gh label list) and prefer them over this default taxonomy.

Type: feature, enhancement, bug, chore, docs, test
Area: frontend, backend, database, infrastructure, security
Priority: priority:high, priority:medium, priority:low
Estimate: points-1, points-2, points-4, points-8 (issues); epic with no points-* label (epics, whose points are the sum of their children)

Estimation Guidelines

Size every issue with the estimating-work-items skill: score effort, complexity, and uncertainty, triangulate against reference stories, and pick one bucket on the powers-of-two scale.

| Points | Kind | Rule | |--------|------|------| | 1, 2, 4, 8 | issue | 8 is the ceiling for a single issue | | Sum of children, no limit | epic | Anything bigger than 8. Never created as a plain issue. Label it epic and decompose it into children of 8 or less; a child bigger than 8 is decomposed again |

An epic is not estimated directly. After decomposing it, add up the children: the exact sum, unrounded and uncapped, is the epic's points. Points are relative size, not days; timeline-planning owns the conversion to durations.

Best Practices

Start with the foundation - Setup and infrastructure issues first
One concern per issue - Each issue does one thing well
Clear acceptance criteria - Know when it's done
Explicit dependencies - Note what blocks what
Honest estimates - Name the main unknown in the Estimate section instead of padding the number
Consistent labels - Use established taxonomy
Link related issues - Cross-reference for context

Example Decomposition

See example.md for a worked decomposition of "Build a user authentication system" (an epic) into 7 issues totalling 18 points.

After Decomposition

Once issues are created:

Suggest running dependency-mapping skill to visualize relationships
Suggest running timeline-planning skill to create a Gantt chart
Offer to save the decomposition summary for future reference

Agent Skills: Issue Decomposition Skill

Install this agent skill to your local

Skill Files