richfrem/user-story-capture

User Story Capture

Derive structured user stories and acceptance criteria from exploration session captures.

Usage

python ./scripts/execute.py \
  --input <file> [<file2>...] \
  --format <standard|gherkin> \
  --output <output_file.md>

Formats:

• standard (default): As a [user type], I want [goal], so that [benefit] — with priority table and gaps.
• gherkin: Standard + Given / When / Then Acceptance Criteria blocks per story.

Flags:

• --input PATH [PATH ...] : Session brief, BRD draft, prototype notes, or prior captures
• --output PATH : Destination file (default: exploration/captures/user-stories-draft.md)
• --format FORMAT : Output format (default: standard)

Interactive Co-Authoring Workflow

When invoked interactively, follow this 3-stage pattern. Do not dump a full story list at once.

Stage 1: Context Gathering

Ask all three questions in a single message before generating anything:

1. Input files: Which source documents should I work from? (Check exploration/ — list what you find: session brief, BRD draft, prototype notes.) If no files exist, stop and ask for input before proceeding.
2. Primary actor: Which user role, system actor, or job-to-be-done is the highest priority for the first implementation slice? (Use role-neutral language — e.g., "the person approving requests", "the agent running evals", not just "the user".)
3. Out-of-scope: Are there any actors or workflows we should explicitly exclude from this story set?
4. Format: Should acceptance criteria use standard format (As a / I want / So that) or Gherkin (Given / When / Then)? Default to standard unless Gherkin is requested.

After the user responds: read each input file they identify.

Stage 2: Iterative Refinement

Build the backlog in layers — do not jump straight to full Gherkin blocks.

1. Outline first: Based on the input files and primary actor, present a numbered list of lightweight story titles (one line each, no ACs yet). Ask: "Which of these should we keep, cut, or merge for the first slice?"

2. Curate: Apply changes. Mark any story derived from unclear or inferred source material as [UNCONFIRMED].

3. Draft approved stories: For each kept story, write the full format:

   • Standard: As a [actor], I want [goal], so that [benefit].
   • Gherkin: Add Given / When / Then AC blocks after the story statement.

   Gherkin format rules:

   • Given = precondition or system state before the action (what is already true)
   • When = the single action or event the actor performs
   • Then = the observable, testable outcome (what changes or appears)
   • One When per scenario. Use And for additional Given or Then clauses.

   Present each story and ask: "Accurate? Anything to add or change?" Apply edits before the next story.

Stage 3: Reader Testing (Test-Driven ACs)

After all approved stories are drafted:

1. For each priority story (top 3 if there are many), predict exactly 2 edge cases or failure modes that a QA engineer would test but that the current ACs do not cover. An edge case must be specific and testable — not generic ("what if it fails?") but concrete ("what if the file is missing at sync time?").
2. Present the gaps: "Story [N] doesn't handle: [edge case 1], [edge case 2]. Should we add scenarios for these?"
3. If yes: add Given / When / Then blocks for the confirmed edge cases. Mark inferred edge cases [UNCONFIRMED] until the user confirms they are real scenarios.
4. Collect all unresolved questions in a ## Story Gaps section at the end.

Anti-Hallucination Rules

• Do NOT invent user types, goals, or benefits not described in source captures.
• Do NOT fabricate edge cases in Gherkin AC without evidence from input files or explicit user confirmation.
• Mark inferred stories and scenarios [UNCONFIRMED] — only promote to [CONFIRMED] after human sign-off.
• Do NOT proceed without input files — stories generated from nothing are pure hallucination.
• Source citations required: each story must note which input file it derives from (e.g., (source: brd-draft.md, Functional Requirements)). Stories with no traceable source must be marked [UNCONFIRMED — inferred, not in source].
• ## Story Gaps section is mandatory — list every open decision or missing actor definition exactly once.

<example> Context: BRD draft is complete, user wants a core story set. user: "Generate user stories from our BRD." assistant: "I'll run `user-story-capture` in standard format to derive a prioritised story set." </example> <example> Context: User wants stories with ready-to-use Acceptance Criteria. user: "Create Gherkin acceptance criteria for these requirements." assistant: "I'll run `user-story-capture --format gherkin` to produce stories with Given/When/Then AC blocks." </example> <example> Context: Pre-sprint refinement. user: "Write acceptance criteria for the checkout flow stories." assistant: "I'll use `user-story-capture --format gherkin` with the checkout BRD sections as input." </example>