Create Stories

Create Stories

The "Create Stories" skill is a specialized utility for the Happycapy Skills platform, designed to transform a single epic into a set of implementable story files. Each of these stories is meticulously crafted to be small, self-contained, and directly traceable to both the Game Design Document (GDD) requirements and Architecture Decision Records (ADRs). This ensures a robust, auditable development process that bridges the gap between high-level architectural planning and actionable development tasks.

What Is This Skill?

The "Create Stories" skill automates the decomposition of an epic-a major feature or capability defined at the architectural level-into discrete, actionable story files. Each story file corresponds to a single implementable behavior, suitable for completion in one focused development session. This skill reads the full context of the epic, including its GDD, relevant ADRs, and the control manifest, then generates story files that embed critical traceability information:

• GDD requirement TR-ID
• ADR guidance
• Acceptance criteria
• Story type
• Test evidence path

The output consists of Markdown files in the directory production/epics/[epic-slug]/story-NNN-[slug].md, where each file follows a consistent, traceable format. The skill is designed to be run after the /create-epics step and should precede story readiness and development steps such as /story-readiness and /dev-story.

Why Use This Skill?

Decomposing epics into stories is a foundational practice in modern agile development. The "Create Stories" skill brings several key benefits to your workflow:

• Traceability: Each story is explicitly linked to a GDD requirement and ADR, establishing a clear audit trail.
• Consistency: The skill enforces uniform formatting and content, reducing ambiguity for developers.
• Automation: Manual splitting of epics is error-prone and time-consuming. This skill speeds up the process while maintaining quality.
• Review Control: The review mode can be set globally or per-run, ensuring that story generation aligns with team QA policies.

By using this skill, teams ensure that every piece of work is rooted in design intent and architectural guidance, minimizing rework and enhancing delivery confidence.

How to Use It

The skill is invoked with the following syntax:

/create-stories [epic-slug | epic-path] [--review full|lean|solo]

• epic-slug or epic-path identifies the target epic for decomposition.
• The optional --review flag specifies the review mode for this run:
  • full: Comprehensive review
  • lean: Minimal gate checks
  • solo: No collaborative review

If the --review flag is omitted, the skill reads the default mode from production/review-mode.txt (defaulting to full if the file is absent). The review mode determines the rigor of gate checks before each story file is generated, following the conventions described in .claude/docs/director-gates.md.

Example Usage

Suppose you have an epic with the slug combat-system:

/create-stories combat-system --review lean

This command will:

1. Parse the epic and its associated documentation.
2. Decompose it into individual stories, each documented as a Markdown file.
3. Apply the "lean" review mode for all gates triggered during this run.

Each generated story file, such as production/epics/combat-system/story-001-attack-action.md, will include:

---
TR-ID: GDD-REQ-123
ADR: ADR-45
Type: gameplay
Acceptance Criteria:
  - The player can initiate an attack by pressing the "A" key.
  - The attack deals damage if an enemy is within range.
Test Evidence: tests/combat/attack-action.spec.js
---

When to Use It

Use the "Create Stories" skill after you have defined epics using the /create-epics command. Always process Foundation epics first, followed by Core and other categories, in order of dependency. This ensures that prerequisite layers are in place before dependent stories are generated.

Invoke the skill once per epic, not per layer, to avoid duplicate or disjointed story files. After running this skill, proceed to review story readiness with /story-readiness [story-path] and then hand off to developers via /dev-story [story-path].

Important Notes

• Strict Order: Always process epics in dependency order. Generating stories for higher-level epics before Foundation epics can lead to missing prerequisites and circular dependencies.
• Review Mode Enforcement: Be explicit with the review mode or ensure that the default is set in production/review-mode.txt. The review mode governs the gate checks applied during story creation.
• Single Responsibility: This skill is intended for use with one epic at a time. Do not attempt to batch multiple epics in a single invocation.
• Traceability: Each story must be traceable to both a GDD requirement and an ADR. Missing links should be flagged for review.

By integrating the "Create Stories" skill into your workflow, you transform high-level architectural intent into actionable, reviewable development tasks, enabling consistent and efficient progress from design to implementation.