name: user-story-writing description: Transform requirements into user stories for coding tasks

Objective

Transform high-level, fuzzy requirements into precise, well-structured user stories that an Orchestrator can decompose into coding tasks.

The output is a user story artifact — a markdown document, git-tracked, treated with the same rigor as code. One story document per task; one cohesive capability per document. A capability is the document's scope. Individual user stories are its constituent parts — each story maps to one Coder-sized unit of work.

Trigger

Use this skill when:

• Orchestrator creates a story-writing task (Liza mode)
• User asks to write user stories for a feature, capability, or requirement (Pairing mode)
• The team's workflow uses user stories rather than formal PRD requirements

Inputs

Your task provides:

• An output file path assigned by the Orchestrator on the blackboard
• References to one or more sections of source material (vision doc, prior specs, existing code)

Scope discipline (two-tier):

• Upfront: Read task references and scan existing stories in the same domain for consistency. Same domain = same stories/ subdirectory, or stories referenced by the same vision doc section. This minimal consistency check is always permitted.
• Reviewer-driven: Broader expansion (new source material, adjacent codepaths, external docs) only when the Story Reviewer's feedback identifies specific additional material to consult.

In both cases, declare what you read and why in the References section.

Output Format

Produce a markdown file at the path specified by the task. Use the User Story format template.

Protocol

1. Parse

Read the source material. Identify what is said, what is implied, and what is missing. Do not start writing stories until you can distinguish the three.

Identify the personas. If the source material does not name them, infer the minimum set from the actions described. A story without a clear persona is a sign that the requirement is not yet understood from the user's perspective.

A useful persona drives design decisions. "User" tells the Coder nothing about context, expectations, or constraints. Include environment and skill level when they affect how the feature should behave. Compare: "User: a person managing their todo list" vs. "Terminal User: a developer or power user who manages personal tasks from the command line and expects standard CLI conventions (flags, non-zero exit codes, concise output)." The second persona tells the Coder that --help should exist and errors should go to stderr.

If the source material contains multiple independent capabilities, flag this to the Orchestrator — it may need to split the task. Do not silently produce a mega-document.

2. Write

Every user story follows the canonical form:

As a , I want to , so that <outcome/value>.

Before writing each assumption, check:

• System quality nobody would dispute? → NFR, not assumption.
• Specifies a data type, format, or representation? → Design territory. State the behavioral need only.
• Provides an answer that an Open Question also asks? → Keep the OQ, drop the assumption.
• Another aspect of the same source gap is already an OQ? → The assumption needs a clear conventional default to justify different treatment; otherwise, prefer OQ for consistency.

Apply SMARC to every user story — Specific, Measurable, Achievable, Relevant, and:

• Context-bound — implementable within the context budget of a single agent task; if a story would force the Coder to load excessive context (many files, large dependency graphs, deep cross-component knowledge), it must be split into smaller stories

If you cannot make a story SMARC, it becomes an Open Question — never a vague story.

References: Each story must trace to its source material. A story with no traceability is Scope Absorption.

Declared dependencies: Verify they are true ordering constraints. ST-X depends on ST-Y only if ST-X cannot be implemented or tested without ST-Y existing. Shared concepts do not imply implementation ordering.

Assumptions are first-class outputs that resolve behavioral ambiguity, not technical. Well-identified LOW-confidence assumptions are more valuable than papered-over gaps. If an assumption names a data type, format, encoding, storage engine, library, or protocol — state the behavioral need only. If it describes a quality nobody would dispute (persistence, latency, error reporting) — it's an NFR.

Acceptance criteria are contracts. They define done. A Coder who satisfies all ACs has completed the story. If your ACs don't fully define done, your story is incomplete.

Acceptance criteria are user-observable. Every AC must describe something the persona can see, do, or experience. Internal system behavior that has no user-visible effect is not an AC — it may be a technical task or an NFR, but it is not a story-level acceptance criterion.

Edge cases are AC variants. Use the AC-NNN-Nb suffix (e.g., AC-001-1b) for edge cases of a parent AC. Edge cases cover error states, boundary conditions, and unexpected input — not just the happy path. Each edge case states expected behavior explicitly.

3. Self-Review

Before submitting for review, verify:

• Every story traces to a source reference (not invented, as granular as possible)
• Every story has a clear persona, action, and value statement
• Persona includes environment or skill-level detail when it affects feature behavior
• Every AC maps to its parent story and describes user-observable behavior
• No LOW-confidence assumptions leaked into stories (they belong in Assumptions)
• Out of Scope is explicit — not just what's excluded, but adjacent concerns the Coder might drift into
• A Coder reading only this document and the referenced files can implement it (no hidden context dependencies)
• Re-read the source material — did you miss anything? Did you add anything not in scope?
• No assumption prescribes implementation (data types, formats, libraries) or states something nobody would dispute (reclassify as NFR)
• No assumption overlaps with an OQ — if overlap exists, keep the OQ and drop the assumption
• Every AC traces to stated or implied source behavior — unmentioned scenarios belong in Assumptions or Open Questions, not ACs
• No OQ contradicts or is resolved by an existing story — if so, either the story is premature or the OQ is unnecessary
• Error states and boundary conditions are covered — not just the happy path
• Dependencies are true ordering constraints, not merely shared concepts
• Sibling ambiguities from the same source gap treated consistently — mixed OQ/assumption requires a clear conventional default

If self-review reveals issues, fix before submitting.

Constraints

• DO write for the Coder, not for management. Be precise and technical. Avoid marketing language, hedging, and filler.
• DO check existing stories in the same domain for consistency — contradictions between story documents are costly to discover at implementation time.
• DO surface inconsistencies as an Open Question if references contradict each other.
• DO NOT write code — stories only.
• DO NOT modify existing story documents unless the task explicitly scopes an update.

Anti-Patterns

• Persona Laundering: "As a user, I want the system to use JSON storage" — persona is a fig leaf on a technical task.
• Giant Story: Can't be implemented in a single focused session? Split it.
• Wishful Story: No testable ACs. "As a user, I want the app to be fast" is not a story.
• Hidden Coupling: References other components' behavior without declaring the dependency.
• Assumption Burial: Assumptions embedded in stories instead of surfaced in the Assumptions section.
• Scope Absorption: Source says "support X." You write stories for X, Y, and Z. Stick to what the task scopes.
• Premature Solutioning: ACs or assumptions that prescribe implementation. "Given the JSON file exists" is solutioning; "Given tasks were previously saved" is behavioral. "Priority is a numeric value where lower = higher" is solutioning; "Priorities have a defined sort order" is behavioral.
• Generic Persona: "As a User, I want to..." where "User" could be any noun. A persona should tell the Coder about context, skill level, or environment that affects behavior.
• Valueless Story: Hand-waving the "so that" clause. If you can't articulate the value, the story may not be needed.

ID Conventions

All IDs in the user story format use structured prefixes:

Do not invent new prefixes. If something doesn't fit these categories, it likely belongs in Context or is a sign the story needs rethinking.

Integration

Mode-Specific Behavior

Pairing mode: All interactive prompts apply. Present the draft stories for human review before writing the file. Human may redirect scope, resolve Open Questions inline, or confirm assumptions.

Liza mode: Story Writer operates autonomously within task scope.