Shape Epic

Turn a product idea into a fully-defined, buildable epic with its design (a UI prototype, an architecture or design-doc PR, or both), ordered slices, test scenarios, a visual build guide, and a tech lead prompt that hands the epic to developer agents.

Trigger

• /shape-epic — auto-detect what exists, resume from there
• /shape-epic PROJ-XXXX — shape an existing epic
• /shape-epic problem — start from problem analysis
• /shape-epic design (or prototype) — design an existing epic: a UI prototype, an architecture PR, or both
• /shape-epic slices — plan slices for an epic that has its design
• /shape-epic tests — create test scenarios for existing slices
• /shape-epic guide — generate the build guide from existing slices and tests
• /shape-epic handoff — write the tech lead prompt and attach it to the epic

Team config

First, load the team config with roost-config. The tracker and its project are in tracker (its adapter says how keys look), the design system is design, the repos the tech lead reads are repos, and the roadmap question uses roadmap.

Rules for every phase

• End every stop with the exact next step, as a question. When you finish a phase or wait for feedback, the last line names what happens next by phase and skill, so the user knows what "yes" starts: "Next is Phase 4 (slices): I'll split PROJ-2961 into stories from the prototype. Start it, or change the prototype first?" Never end on "let me know" or "what next?".
• Every question comes with your recommendation and why. List the options with the recommended one first, so the user can answer with a letter. A question without a recommendation costs them a round trip.
• Scope changes only when the user decides. Anything you find while shaping that isn't part of the epic (a bug in existing code, a refactor, a gap in another feature) goes to the user as a proposed ticket: what it is, the evidence (file:line), and a recommendation (its own Bug, under this epic, or leave it). Don't fold a fix into the design, the slices or the description until they decide, and file the ticket once they do.
• Work no repo session can do (a PR to another company's repo, a video, a partner conversation, a launch post) is a person-owned task: see phase 4.

Phases

The skill has seven composable phases. Each phase produces artifacts that feed the next. You can enter at any phase if the prerequisites exist.

problem → epic → design → slices → tests → guide → handoff

Before starting a phase, read its steps file in full and follow it. Each file holds that phase's process, guidance and expected output.

Auto-Detection

When invoked without a specific phase, inspect what exists and recommend where to start:

1. No epic key provided: Ask if they have an existing epic or want to start from a problem statement.
2. Epic key provided: Fetch the epic and its children from the tracker.
   • Has stories under it? Skip to phase 5 or 6.
   • Has tests? Skip to phase 6.
   • Has a build guide but no <EPIC> Tech Lead Prompt.md attachment? Skip to phase 7.
   • Has only a description? Start at phase 3 (design) or phase 4 (slices).
3. Present what you found and propose the next phase. Let the user override.

I found PROJ-1768 with:
  ✓ Rich epic description (goals, scope, technical context)
  ✓ 5 stories (PROJ-1771 through 1775)
  ✓ 9 test issues
  ✗ No build guide artifact

Recommended next step: Phase 6 (Build Guide)
Want to proceed, or would you rather revisit an earlier phase?

Resuming Partially-Defined Epics

This skill is designed for epics at any stage of definition. Common entry points:

When entering mid-stream, always inventory what exists before proposing new work. Don't recreate what's already there.

Quality Checklist

Before declaring a phase complete:

• User has reviewed and approved the output
• All tickets have rich descriptions (not just titles)
• Stories are ordered and independently shippable
• Tests cover every acceptance criterion in every slice
• Cross-cutting tests are identified and mapped to their last dependency
• The build guide accurately reflects the current state of all slices and tests
• The epic has the build guide, the prototype (if it has one) and the tech lead prompt attached, and a comment linking any design PR
• The tech lead prompt has no unfilled placeholders, and every "In this epic" line comes from this epic's own sources

References

• See references/epic-description-template.md for the recommended epic description structure
• See references/slice-checklist.md for the slice quality checklist
• See references/tech-lead-prompt-template.md for the Phase 7 prompt template and how to fill it
• See references/phase-<n>-<name>.md for each phase's steps
• The tests adapter's "Create a test" says how Phase 5 creates tests
• The skill named in roadmap.skill, if any, puts an epic on the roadmap