generate-user-stories

name	generate-user-stories
description	Turn the greenfield brainstorm report (+ source manifest) into a standalone user-story-list.md — the S2 deliverable that otherwise only exists buried in SRS §3. Confidence-gated co-creation: self-scores each story (source/completeness/interpretation) + a coverage map, runs scoped human Q&A only where unsure (reusing clarification-loop), then a confirm gate — depth adapts to G1 quality. Two output formats via --format brse|agile: brse = function-list rows aligned 1:1 with SRS §3.1 (JP ITO clients); agile = As-a/I-want/So-that with acceptance criteria. Both map cleanly to ProjectModel FunctionalRequirement / UseCase for the bridge.
category	documentation
keywords	["user-stories","function-list","brse","agile","srs","greenfield","requirements"]
argument-hint	--workspace morkit/output/greenfield/<proj> --format brse|agile [--lang JP|EN|VN]
metadata	{"author":"morkit-greenfield","version":"1.0.0"}

Generate User Stories

Stage G2 of /morkit:greenfield. Reads what was learned at G1 and emits the user-story list the rest of the pipeline (G3 gap-risk, G5 bridge) attaches to.

Conventions: ../greenfield-orchestrator/references/greenfield-conventions.md. Confidence rubric (scoring + question templates): references/confidence-rubric.md. Templates: templates/user-story-brse-template.md, templates/user-story-agile-template.md.

Shared item shape (one model, two renderers — DRY)

Internally every story is the same item; --format only picks the renderer:

{ id, title, actor, goal, benefit, acceptance, priority, source_ref,
  source_strength, field_completeness, interpretation }   # last 3 = G2 self-score (working metadata)

The first 8 fields render into user-story-list.md; the last 3 are confidence metadata (see rubric) that drive B2–B3 and the gate review-aid — not rendered.

• brse renders the function-list table (columns mirror SRS §3.1).
• agile renders the As-a / I-want / So-that table with acceptance criteria.

Because both are views of one item shape, the bridge maps either to ProjectModel without loss — formats can't drift.

Inputs

From the run workspace morkit/output/greenfield/<proj>/:

• brainstorm-report.md (G1) — the candidate stories' source.
• source-manifest.json — provenance refs to cite per story.

Procedure — confidence-gated co-creation

G2 is gated (the function list is the foundational doc everything downstream is built on). Rather than auto-emit and hope, self-score confidence and spend human attention only where it's unsure. Rubric + question templates: references/confidence-rubric.md.

B1 — Draft with source discipline (kills fiction). Extract candidate stories from brainstorm-report.md (+ manifest facts). Assign deterministic, stable ids (FUNC-001… brse / US-001… agile) in document order; re-runs reuse existing ids (same pattern as docs-hero-orchestrator/scripts/lib/id_allocator.py). Every row MUST carry a Source and is doc_status: Draft. Assert 0 stories without source_ref — a sourceless candidate becomes a B3 question or a G3 gap, never a row.

B2 — Self-score + coverage map (detects shallow / missing / wrong). Per story set source_strength, field_completeness, interpretation per the rubric. Build the coverage map of function-areas (from actors/scope/modules in G1) and mark zero-story areas. Flag any story with a low/weak/inferred signal.

B3 — Scoped interactive Q&A (the co-creation; reuse clarification-loop). For flagged items only, write grouped questions into g2-clarification-log.md using the same table shape as clarification-loop's clarification-log-template.md (do not invent a second format). High-confidence stories are listed for awareness, not interrogated (respect the BrSE's time). Ingest answers → update the affected stories → re-score. This loop is interpretation/coverage-driven and runs before G3 — distinct from G4 (gap-driven, after G3); the separate log file keeps them from colliding.

B4 — Render + review-aid (feeds the G2 gate). Render the selected --format into user-story-list.md, then emit the review-aid summary (rubric §"Review-aid summary"). The orchestrator runs the G2 confirm gate (Proceed / Another round = re-run B2–B3 / Abort) and persists it via state_manager set-gate --stage G2. This skill produces the artifact + review-aid; it does not run the gate UI itself.

Bridge mapping (consumed at G5)

Format	ProjectModel target
brse row	FunctionalRequirement (id from Related FR / derived from FUNC-id; name=Function; role=Actor; priority; source; doc_status: Draft)
agile row	UseCase (id UC-00x; name=goal; actor=role; summary=benefit; main_success_scenario=acceptance) + a derived FR when the story implies a concrete function

Verify every required FR/UseCase field is populated before handing to the bridge (see ../build-project-model/references/schema-cheatsheet.md).

Format choice

--format is inherited from state.json (set at G0; default brse for JP ITO). The orchestrator passes it through; this skill never decides format on its own.