Story Specify

story-specify

Input: $ARGUMENTS (story description — use conversation text if literal). Output: [STORY_DIR]/spec.md. Template: .speck/templates/story/story-template.md.

0. Template

Before any mutation, run python3 .speck/scripts/context/speck_context.py story-specify. Require exit 0 and SPECK_CONTEXT_RECEIPT; follow the receipted story template.

1. Play level

Read .speck/project.json → play_level.

2. Context

Parse args: project:XXX epic:YYY [description] or ask progressively.

List options:

find specs/projects -name project.md -exec dirname {} \; | xargs -I {} basename {}
ls specs/projects/[PROJECT_ID]/epics/

Before any story mutation in Build or Platform, prove the parent epic analysis gate:

bash .speck/scripts/validation/validators/validate-project-analysis.sh --gate "$EPIC_DIR"

STOP on non-zero. Build requires the focused epic lens; Platform requires all seven. Re-run this as a separate command after the final story-corpus mutation and template validation so the completed transcript proves the parent gate still cleared.

3. Placeholder detection

SPEC=$(ls -1 specs/projects/[PROJECT_ID]/epics/[EPIC_ID]/stories/[STORY_ID]-*/spec.md 2>/dev/null | head -1)

CRITICAL: never drop depends_on — orchestrator reads it.

4. Pre-validation

Check epic-breakdown.md + stories/ for duplicates. Story-level? (5-min explainability) vs epic-level?

Load: domain-model.md, ux-strategy.md, design-system.md, epic.md. Misaligned → offer different epic / expand epic.

5. Specify

Enhance draft: show content; refine gaps. Fresh: gather user story, triggers, completion signals, stable AC-N scenarios in the template's GIVEN/WHEN/THEN grammar, constraints, test approach, FE/BE scope, API/DB impacts.

mkdir -p specs/projects/[PROJECT_ID]/epics/[EPIC_ID]/stories/[STORY_ID]-[name]

Fill template → spec.md:

**Current State**: Specified
- [x] **Draft** (if was placeholder)
- [x] **Specified**

Before save, require all four: canonical frontmatter lifecycle_state: Specified; stable AC-N scenarios with observable outcomes; named failure behavior; and a concrete test/LARP approach for every failure. Preserve depends_on and blocks byte-for-byte unless the epic breakdown has also been deliberately amended.

Preserve requirement fidelity. A new required field, actor, integration, or solution choice must trace to the epic/breakdown/input; otherwise mark it [NEEDS CLARIFICATION] instead of inventing it. Give every named failure path a negative acceptance criterion and matching test/LARP approach.

Update the epic story list to mark this story specified before closing the story-specification corpus.

After all spec.md and epic story-list edits, run the validator as a standalone command event:

bash .speck/scripts/validation/validate-template.sh "$STORY_DIR/spec.md" --strict
bash .speck/scripts/validation/validators/validate-project-analysis.sh --gate "$EPIC_DIR"

Do not chain, pipe, or wrap either gate, and do not mutate the story corpus afterward. Each recorded event exit must belong to its validator.

5-minute test: explain in <5 min. Needs "AND" or >3 AC scenarios → split.

6. Optional step evaluation

Output table with evidence quotes + recommended path.

Continuation:

• Orchestrated (/story): proceed to first recommended step
• Interactive: ask "Proceed with [first step]?"

After save, re-read the marked canonical Story flow in root AGENTS.md and continue at its first incomplete applicable slot. The table selects optional slots; it does not define their order.

UI REQUIRED: note /story-ui-spec after plan, before tasks.

NEVER / ALWAYS

• NEVER overwrite depends_on / blocks frontmatter
• NEVER create duplicate stories without user approval
• NEVER skip template read
• ALWAYS run optional step evaluation after save
• ALWAYS preserve placeholder progression in lifecycle checkboxes