Basinfy/Basinfy-SaaS-Studio / .claude/skills/saas-create-stories
saas-create-stories
VerifiedBreak an epic into implementable stories with Gherkin acceptance criteria and ADR refs.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.7 KB |
| references/qa-lead-gate.md | markdown | 3.1 KB |
SKILL.md
View on GitHub---
name: saas-create-stories
description: "Break an epic into implementable stories with Gherkin acceptance criteria and ADR refs."
argument-hint: "[epic-slug | epic-path] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/saas-create-stories/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/adr-status.sh *), Bash(bash .claude/scripts/md-section.sh extract *), Bash(bash .claude/scripts/md-section.sh list *), mcp__basinfy__basinfy_query_script, mcp__basinfy__basinfy_discover, mcp__basinfy__basinfy_prepare_edit, mcp__basinfy__basinfy_prepare_create, mcp__basinfy__basinfy_impact, mcp__basinfy__basinfy_remember, mcp__basinfy__basinfy_recall, Bash(basinfy *)
model: sonnet
---
!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys locale,review_mode,review_gate,automation,workflow,docs.density,story_granularity,qa.level,system_overrides`
Resolved above — use as-is; `--review` overrides `review_mode`. No block →
defaults in `.claude/docs/config-resolution.md`.
Ask with the question tool. Without one, list the options numbered and end your turn
to wait. A skipped or dismissed question is not an answer: ask again in plain text.
# Create Stories
> **Locale & User Profile**: Match `locale` (`pt-BR` → natural Brazilian Portuguese questions/options, overriding English examples; `en` → English) and `user_profile` (`founder` → plain business language with `(Recomendado)` first, zero tech jargon; `developer` → technical). Keep code/tests in English.
A story is one implementable behaviour: small enough for the size
`story_granularity` sets, self-contained, and traced to a requirement and the
decision that governs it. Run this skill once per epic, in dependency order:
Foundation epics first, then Core, Feature, Presentation.
**Writes:** `production/epics/[epic-slug]/story-NNN-[slug].md`, the epic's
`EPIC.md` Stories table, and its row in `production/epics/index.md`.
**Next:** `/saas-dev-story [story-path]` at `workflow: minimal`; otherwise
`/saas-story-readiness [story-path]`, then `/saas-dev-story`.
Asks follow `.claude/docs/automation-modes.md` (collaborative always asks, guided
asks on major choices, autonomous logs and goes on; `automation_always_ask`
categories always ask).
Checklist (copy it and tick as you go):
```
- [ ] Phase 1: epic found, tier resolved
- [ ] Phase 2: inputs loaded, each ADR's status reported
- [ ] Phase 3-4: stories drafted, typed, Ready or Blocked
- [ ] Phase 5: QA lead review run, or its skip noted
- [ ] Phase 6: story list shown, one ask to write
- [ ] Phase 7: stories, EPIC.md and index.md written (or index absence said)
- [ ] Phase 8: next step asked, closing block printed
```
## Phase 1: Epic and settings
**Tier.** `workflow` for the epic's system: the `system_overrides` row for the epic
slug (its PRD system) if there is one, else the project value.
**`story_granularity`** sets each story's acceptance-criteria load. Group or split
criteria to hit it:
| `story_granularity` | ACs per story | Size |
|---|---|---|
| `coarse` (default, `rigor: minimal`) | 5-10 | a whole feature, multi-day |
| `balanced` (`rigor: standard`) | 2-4 | one task, about one session |
| `fine` | 1 | one criterion; the story name restates it |
**`docs.density`** sets the depth of each story's prose (context, implementation
notes, ADR summary), never the AC count or the AC text: `terse` (default) = bullet
notes, no preamble; `balanced` = a short context paragraph plus notes; `thorough` =
full context, guidance and ADR rationale. The TR-ID, ADR Version and acceptance
criteria are never trimmed.
**Which epic.** The text typed after the skill name, with any `--review <mode>`
pair removed: an epic slug (`billing`) or a path (`production/epics/billing/EPIC.md`).
With nothing typed, the epic the user's request names ("the billing epic") counts as
named.
- **Named, but no `EPIC.md` there:** at `standard` and `full`, stop: "No epic at
`production/epics/[slug]/EPIC.md`. Run `/saas-create-epics` to create it, or check the
slug with `ls production/epics/`." Never decompose from a guess. At `minimal`,
say this tier needs no `/saas-create-epics` epic, take Phase 2's `minimal` branch, and
name the slug it uses.
- **Blank, at `minimal`:** take Phase 2's `minimal` branch.
- **Blank, at `standard` or `full`:** list `production/epics/*/EPIC.md` with each
status, then ask: "Which epic would you like to break into stories?" with one
option per epic. **No epics found:** stop and say "No epics found under
`production/epics/`. Run `/saas-create-epics layer: foundation` first." Never ask a
question with no options.
## Phase 2: Load the inputs
### `minimal`: build the epic from the brief
1. **No `design/product-brief.md`:** stop. "There is no brief to build stories from
yet: run `/saas-brainstorm` first; it writes the one-page brief." When the code root
already holds the application (10 or more source files), name `/saas-reverse-document design
[code root]` instead.
2. Read `design/product-brief.md` in full (one page).
3. **The epic.** `<slug>` is the brief's working title, slugified (`mvp` if it has
none), or the epic the user named.
- `production/epics/<slug>/EPIC.md` exists: it is the epic. Use its scope, still
traced to the brief, and never rewrite it.
- It does not: draft one, written in Phase 7 only after the Phase 6 ask names
it. Goal = the brief's one-sentence pitch; scope = its MVP feature list;
order = its **Build order**. Keep it terse.
- Stories already in the folder (a return visit): never rewrite an existing
`story-*.md`. Add stories only for brief items they do not cover, or new ones
the user names, and number on from the highest existing `story-NNN`.
4. **One story per MVP feature, in Build order**, each traced to the brief. No
story is blocked on ADR grounds: this tier has none.
Read no PRD, control manifest, TR registry or ADR at `minimal`. Go to Phase 3.
### `standard` and `full`: the epic and what governs it
1. **The epic:** `production/epics/[epic-slug]/EPIC.md` in full (its layer, PRD,
governing ADRs, and the PRD Requirements table with TR-IDs).
2. **The PRD:** its sections by heading, never the whole file:
`bash .claude/scripts/md-section.sh extract design/prd/[file].md "Acceptance Criteria"`,
and the same for `Formulas`, `Edge Cases` and `Detailed Design` (exit 3: try
`Detailed Rules`, the design standard's name for the same section); at `full`
the other required sections too (`list` shows the headings).
3. **The control manifest:** the epic's layer only, and the version:
`bash .claude/scripts/md-section.sh extract docs/architecture/control-manifest.md "[Layer] Layer Rules"`,
plus its `Manifest Version` line.
4. **The TR registry:** this system's entries only: in
`docs/architecture/tr-registry.yaml`, the lines matching `system: <slug>\s*$`,
with each entry's `id` above and its text below. The anchor keeps `billing` from
matching `billing-ai`; `\s*` takes a Windows line ending.
5. **The ADRs**, every one the epic names (governing, or in its requirements table,
Proposed ones included), in one call:
```
bash .claude/scripts/adr-status.sh ADR-0001 ADR-0003 ...
```
Each row gives the status, layer, `version` (the story's ADR Version stamp),
`depends_on`, and missing sections. Then read only `Summary`, `Decision` (its
Implementation Guidelines inside) and `Engine Compatibility` of each, with
`md-section.sh extract`. Engine Notes is a story field taken from Engine
Compatibility, not an ADR section. An ADR with none of these sections predates
the template: read it once, and flag it for `/saas-architecture-decision retrofit
[file]`.
**A named ADR with no file** (`NOT_FOUND`):
- `full`: stop before decomposing any story.
- `standard`: stop only when it is critical (Foundation layer); otherwise warn, go
on, and write the stories it governs as `Blocked` until it exists.
- On stopping: "Epic references [ADR-NNNN: title] but no file for it was found in
`docs/architecture/`. Check the epic's Governing ADRs list, or run
`/saas-architecture-decision` to create it. Cannot create stories until the
referenced ADR files exist."
**Report before drafting**, with the real state, every ADR on its own with its
status:
```
Loaded: epic [name] · PRD [file] · manifest v[date], [layer] rules
ADRs: ADR-0001 Accepted · ADR-0002 Accepted · ADR-0003 Accepted · ADR-0004 Proposed · [ADR-NNNN missing]
```
Never say "all present" when one is missing, or name a manifest version when there
is none.
## Phase 3: Type each story
| Type | When its criteria reference |
|---|---|
| **Logic** | formulas, thresholds, state transitions, business rules, calculations |
| **Integration** | two or more services, API contracts across boundaries, persistence/hydration round-trips |
| **Visual/Feel** | animation, UI transitions, "feels responsive", timing, loading states, micro-interactions |
| **UI** | navigation, App Shell, buttons, screens, modal dialogs, tooltips |
| **Config/Data** | configuration settings and schema migrations only, no new logic |
A mixed story takes the type with the highest implementation risk. The type sets
the evidence `/saas-story-done` needs.
## Phase 4: Draft the stories
Group the requirements that need the same core implementation into one story, at
the `story_granularity` load. Order: foundation behaviour first, edge cases later,
UI last. For each story:
- **Requirement:** the TR-ID from the registry, matched through the epic's PRD
Requirements table. Only when no entry matches, write `TR-[system]-???` and say
so.
- **ADR:** the one that governs how to build it (the requirements table names it).
- `Accepted`: embed it.
- `Proposed`: `Status: Blocked`, with "BLOCKED: ADR-NNNN is Proposed — accept it
with `/saas-architecture-decision accept ADR-NNNN` once decided".
- `Deprecated` or `Superseded`: `Status: Blocked`, with "BLOCKED: ADR-NNNN is
[status] — point the story at [successor] (edit its ADR field;
`/saas-create-stories` never rewrites an existing story) before implementing".
- An `Accepted` ADR whose `depends_on` names an ADR that is not Accepted: Blocked
the same way, naming that ADR.
- Several apply: list them all, the most direct first.
- None applies: `ADR: N/A — [reason]`, e.g. "pure data configuration". Never
blank: blank means unchecked.
- **ADR Version:** the story's **ADR Version** is the ADR's `## Last Verified`
date, else its `## Date`, else `unversioned` (the `version` column). `/saas-dev-story`
trusts the story's ADR summary while this still matches the ADR.
- **Engine risk:** from the ADR's Engine Compatibility (its knowledge risk).
- **Estimate:** propose a t-shirt size from the criteria and the files the story
touches: `S` (a few hours), `M` (about a day) or `L` (several days). It is a
proposal: Phase 6 shows it and the user can change it. `/saas-story-readiness` fails
a story whose Estimate is still the template's bracket, so never leave it.
## Phase 5: QA lead review
Read the `review_gate` line above. `skill-gates=skip` (solo or lean): no review;
note "QL-STORY-READY skipped — [Solo | Lean] mode" in the Phase 6 list and the
closing block. `skill-gates=run`: read `references/qa-lead-gate.md` and
`.claude/docs/director-gates.md`, and run it now, before the Phase 6 ask. On a skip,
do not load it.
## Phase 6: Show the stories, ask once
```
## Stories for Epic: [name]
ADRs: ADR-0001 Accepted · ADR-0002 Accepted · ADR-0004 Proposed (every ADR, from Phase 2)
Story 001: [title] — Logic — ADR-0001 — Ready — Estimate M
Covers: TR-[system]-001 ([one-line requirement])
Test required: tests/unit/[system]/[slug]_test.[ext]
Story 002: [title] — Integration — ADR-0004 — BLOCKED (ADR-0004 is Proposed) — Estimate L
Covers: TR-[system]-002, TR-[system]-003
Test required: tests/integration/[system]/[slug]_test.[ext]
Story 003: [title] — Visual/Feel — ADR-0001 — Ready — Estimate S
Covers: TR-[system]-004
Evidence required: retained screenshot + sign-off in production/qa/evidence/[slug]-evidence.md
[N stories: N Logic, N Integration, N Visual/Feel, N UI, N Config/Data; N Blocked]
QL-STORY-READY: [skipped — Solo mode | its verdicts]
```
At `minimal`, each line traces to `Brief MVP feature N`, there is no ADRs line, and
there is one story per MVP feature: no extra stories for brief items outside the
MVP list. Then
ask: "May I write these [N] stories to `production/epics/[epic-slug]/`, and
[create | update] `production/epics/[epic-slug]/EPIC.md` and update
`production/epics/index.md`?" Options: Yes, write all [N] / Not yet, I want to
adjust first; an adjustment can change any estimate. Name every file Phase 7 touches: *create* `EPIC.md` only when it
does not exist, and leave `index.md` out when it does not exist. Write nothing
before the yes.
## Phase 7: Write
### The story files
**Each story** is `production/epics/[epic-slug]/story-[NNN]-[slug].md`, laid out
as `.claude/docs/templates/story.md`. Never reuse a story number. Write each file
as a file, never through a shell command: a shell write skips the project's write
checks.
At `minimal` there is no PRD, ADR, TR registry or manifest. Fill these fields
exactly:
| Field | Value at `minimal` |
|---|---|
| PRD | `design/product-brief.md` |
| Requirement | `Brief MVP feature N`, never a TR-ID |
| ADR Governing Implementation, ADR Decision Summary, ADR Version | `N/A (minimal — no ADRs)` |
| Manifest Version, Control Manifest Rules | `N/A (minimal — no control manifest)` |
| Engine | `stack.frontend` + `stack.version` |
| Risk | the level `docs/engine-reference/<engine>/VERSION.md` gives the pinned version (its timeline row, or its overall rating). No file or no level: `NOT ASSESSED (no VERSION.md risk rating)`, never a guess. `/saas-dev-story` reads NOT ASSESSED as HIGH |
| Engine Notes | `none (no ADR engine-compatibility analysis at minimal)` |
| Acceptance Criteria | from the brief's **User goal & fail state** and the MVP feature, made concrete and testable; never invented from a bare bullet |
At every tier:
- **QA Test Cases:** when the review was skipped, write
`*N/A — no qa-lead specs at this tier; implement against the Acceptance Criteria above*`.
Never improvise test cases.
- **Test Evidence:** `qa.level` governs it. At `qa.level: minimal` tests are
waived (advisory), but a Visual/Feel or UI story's retained screenshot is not.
- **Estimate:** the size from Phase 6, with any change the user made.
- **Dependencies:** name each story this one needs by its path.
- **Files:** the code and test files the story is planned to create or change,
under the code root and test root. `/saas-dev-story` replaces them with the real list.
### `EPIC.md`
At `minimal` with none yet, write the Phase 2 draft with the table
below. Otherwise replace its "Stories: Not yet created" line with the table, or on
a return visit append one row per new story and leave the rest of the file as it
is:
```markdown
## Stories
| # | Story | Type | Status | ADR |
|---|-------|------|--------|-----|
| 001 | [title] | Logic | Ready | ADR-0001 |
| 002 | [title] | Integration | Blocked | ADR-0004 |
```
### `production/epics/index.md`
Set the epic's `Stories` cell to `[N] stories`,
the epic's total after this run. When the file does not exist, say so:
`Epics index not updated: production/epics/index.md absent`.
## Phase 8: Close
If other epics in `production/epics/` have no stories, list them. Then ask:
"[N] stories written to `production/epics/[epic-slug]/`. What next?" Options, those
that apply:
- Start implementing: `/saas-dev-story [first-story-path]` at `minimal`,
`/saas-story-readiness [first-story-path]` otherwise (recommended)
- Create stories for [next epic]: `/saas-create-stories [slug]` (only when an epic has
none)
- Plan the sprint: `/saas-sprint-plan new` (only when every epic has stories; never at
`minimal`, where the brief's build order is the plan)
- Stop here for this session
Never start implementation or write code: this skill stops at the story files.
Acceptance criteria come from the PRD (the brief at `minimal`), implementation
notes from the ADRs, rules from the manifest; none are invented.
**The run's last reply ends with this block**, after the question above is
answered (repeat it if you showed it earlier):
```
Verdict: COMPLETE — [N] stories written to production/epics/[epic-slug]/ ([N] Ready, [N] Blocked)
Review: [QL-STORY-READY skipped — Solo mode | skipped — Lean mode | its verdicts]
Index: [production/epics/index.md updated | Epics index not updated: production/epics/index.md absent]
Next step: [/saas-dev-story [first-story-path] | /saas-story-readiness [first-story-path]]
```
When the user declines the write: `Verdict: BLOCKED — user declined. No story
files written.`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |