/gaia-add-stories
user-facingWhat it does
/gaia-add-stories adds new stories to existing epics or creates new epics with stories. It appends to the existing document without modifying stories already in progress, in review, or done. Story and epic IDs are auto-incremented from the highest existing ID.
When to use it
- You need to add new stories after initial planning -- for example, after a PRD or architecture change.
- A new feature request needs to be decomposed into stories.
Prerequisites
- Epics-and-stories must exist at
.gaia/artifacts/planning-artifacts/epics-and-stories.md.
How to invoke
/gaia-add-storiesWhat it does step by step
- Load existing state Reads epics-and-stories and sprint status. Builds a protection map: stories in progress/review/done are locked (read-only), backlog stories require confirmation to modify.
- Identify requirements Asks what new stories are needed, whether they belong to existing or new epics, and whether linked to a change request. Reads PRD and architecture for context.
- Epic decision Analyzes fit against existing epics. Recommends: extend existing epic, create new epic, or mixed.
- Create new epic (if needed) Auto-increments epic ID. Defines name, description, goal, and success criteria.
- Define stories For each new story: title (user story format), acceptance criteria, size, priority, risk level, dependencies, and epic assignment.
- Validate and append Validates no ID collisions or circular dependencies, then appends to the document.
Story protection
Stories with status in-progress, review, ready-for-dev, or done are strictly read-only. This command never modifies them.
Inputs
| Input | Source | Description |
|---|---|---|
| Existing epics and stories | .gaia/artifacts/planning-artifacts/epics-and-stories.md | Current epic/story document (required). |
Outputs
| Output | Location | Description |
|---|---|---|
| Updated epics and stories | .gaia/artifacts/planning-artifacts/epics-and-stories.md | Document with new stories appended. |
Example session
> /gaia-add-stories
Existing: 4 epics, 18 stories (3 locked, 15 open).
What new stories are needed?
> API rate limiting and abuse detection
Epic decision: extends E1 (User Authentication).
New stories:
E1-S19: API rate limiting (M, P1, medium risk)
E1-S20: Abuse detection and blocking (L, P1, high risk)
Appended to: .gaia/artifacts/planning-artifacts/epics-and-stories.mdWhat to run next
/gaia-sprint-plan-- plan the new stories into a sprint./gaia-readiness-check-- verify completeness with the new stories.
Troubleshooting
"epics-and-stories.md not found"
Run /gaia-create-epics first.