From super-ralph
This skill should be used when writing epics and user stories from product vision, business goals, or user feedback. Triggers when /super-ralph:design is invoked, or when the user mentions "write epics", "create user stories", "product design", "acceptance criteria", "feature breakdown", "e2e test scenarios", or wants to translate business goals into structured development artifacts. Produces BDD-style acceptance criteria that feed directly into /super-ralph:plan as e2e test scaffolding.
How this skill is triggered — by the user, by Claude, or both
Slash command
/super-ralph:product-designThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Translate product vision, business goals, and user feedback into structured epics and user stories with BDD acceptance criteria. The acceptance criteria serve dual purpose: defining "done" for stakeholders AND generating e2e/behavior test scaffolding for implementation plans.
Translate product vision, business goals, and user feedback into structured epics and user stories with BDD acceptance criteria. The acceptance criteria serve dual purpose: defining "done" for stakeholders AND generating e2e/behavior test scaffolding for implementation plans.
Announce at start: "I'm using the product-design skill to create epics and stories with testable acceptance criteria."
Core insight: Acceptance criteria written in Given/When/Then format are directly translatable to e2e test cases. This creates traceability from business goal to passing test — every story is verifiable by a machine.
Vision / Goals / Feedback
↓ /super-ralph:design
Epic (docs/epics/YYYY-MM-DD-<slug>.md)
├── Story 1 → Acceptance Criteria → E2E Test Skeleton
├── Story 2 → Acceptance Criteria → E2E Test Skeleton
└── Story N → Acceptance Criteria → E2E Test Skeleton
↓ /super-ralph:plan --story <path>#story-N
Implementation Plan (docs/plans/YYYY-MM-DD-<slug>.md)
├── Task 0: E2E test from acceptance criteria (outer RED)
├── Task 1-N: TDD implementation tasks (inner red-green)
└── Final: E2E test goes GREEN
The outer e2e test starts red and stays red until all inner TDD tasks complete. When it goes green, the story is delivered.
Every epic follows the template in references/epic-template.md.
| Epic Size | Stories | Implementation Plans | Suitable For |
|---|---|---|---|
| Small | 2-4 | 1 plan | Single feature or improvement |
| Medium | 5-8 | 1-2 plans | Feature set or workflow |
| Large | 9-15 | 2-4 plans (phased) | Major capability or system |
| Too Large | 15+ | Split into multiple epics | — |
Every story follows the template in references/story-template.md.
### Story N: [Title]
**As a** [persona from product vision],
**I want to** [specific action],
**so that** [measurable outcome].
**Priority:** P0 (must-have) | P1 (should-have) | P2 (nice-to-have)
**Size:** S | M | L | XL
Write every acceptance criterion in Given/When/Then format. Each criterion becomes one e2e test case.
#### Acceptance Criteria
- [ ] **Given** I am on the agent builder page
**When** I select a template and click "Create"
**Then** a new agent is created with the template's default configuration
**And** I am redirected to the agent editor
- [ ] **Given** I have an agent in draft status
**When** I click "Deploy"
**Then** the agent status changes to "Active"
**And** a confirmation message shows the agent's endpoint
Rules for good acceptance criteria:
Generate a test skeleton from the acceptance criteria. This skeleton feeds into /super-ralph:plan as the outer test loop.
// tests/e2e/[story-slug].test.ts
describe("[Story title]", () => {
test("creates agent from template", async () => {
// Given: on agent builder page
// When: select template and click Create
// Then: new agent created, redirected to editor
});
test("deploys draft agent", async () => {
// Given: agent in draft status
// When: click Deploy
// Then: status = Active, confirmation shown
});
});
Read the product vision document and extract:
When input is user feedback or feature requests:
When input is business metrics or OKRs:
When ambiguity arises during epic/story creation — scope boundaries, persona priorities, acceptance criteria precision — apply the same autonomous decision pattern used throughout super-ralph:
When invoking /super-ralph:plan with a story reference:
/super-ralph:plan --story docs/epics/2026-02-16-agent-builder.md#story-1
The plan command should:
| Story Element | Plan Element |
|---|---|
| Acceptance criteria (Given/When/Then) | E2E test cases (Task 0) |
| Priority (P0/P1/P2) | Task ordering |
| Size (S/M/L/XL) | Iteration budget |
| Dependencies | Plan prerequisites section |
docs/epics/YYYY-MM-DD-<slug>.md (create the directory if needed)[EPIC] issue on GitHub with sub-issues for each story (see GitHub Issue Creation section)After writing the epic markdown file, also create GitHub Issues to track the work on the ForthAI Work Project #9 board.
After saving the epic to docs/epics/, create a corresponding [EPIC] issue:
gh issue create \
--title "[EPIC] <Epic title>" \
--label "area/<backend|frontend|fullstack>" \
--milestone "<active milestone>" \
--body "$(cat <<'EOF'
## Goal
<Epic business context — 1-2 sentences>
## Stories
<Checklist of [STORY] items from the epic>
## Epic Document
docs/epics/YYYY-MM-DD-<slug>.md
## Notes
<Dependencies, risks from the epic>
EOF
)" --repo Forth-AI/work-ssot
# Add to Project #9, set fields: Type=epic, Size, Priority
For each story in the epic, create a [STORY] issue:
gh issue create \
--title "[STORY] <Story title>" \
--label "vertical-slice,area/<backend|frontend|fullstack>" \
--body "$(cat <<'EOF'
**Parent:** #<epic-issue-number>
## User Story
**As a** <persona>,
**I want** <action>,
**So that** <outcome>.
## Acceptance Criteria
<BDD criteria from the story>
EOF
)" --repo Forth-AI/work-ssot
# Add to Project #9, set fields: Type=story, Size, Priority
Rules:
[STORY] title prefixgh project item-add 9 --owner Forth-AI --url <issue-url>| Epic Size | Stories | Project Field |
|---|---|---|
| Small (2-4 stories) | 2-4 | Size=L |
| Medium (5-8 stories) | 5-8 | Size=XL |
| Large (9+ stories) | 9+ | Split into multiple [EPIC] issues |
references/epic-template.md — Complete fill-in-the-blanks epic templatereferences/story-template.md — Story template with BDD acceptance criteria and e2e skeletonreferences/acceptance-criteria-guide.md — Detailed guide for writing machine-verifiable acceptance criteriaGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub junhua/claude-plugins --plugin super-ralph