User Story

Follow these steps in order:

1. Check the output configuration. Look for skills.user-story.format in AGENTS.md. If not configured, see template files in format/ (relative to this skill) to present the available options and ask the user to choose before proceeding.
2. Understand the project context. Before writing anything, explore the repository to ground the story in the real codebase. Read the README, scan docs/ or any documentation folder, and skim relevant source files (routes, components, models, config). Look for the tech stack, existing terminology, domain language, feature boundaries, and naming conventions the team already uses. This prevents inventing features that already exist and ensures acceptance criteria reference actual UI labels, page names, and workflows.
3. Identify the user persona, their goal, and the ticket type (Story, Task, or Bug). Use what you learned from the codebase to pick the right persona and to align the story's scope with existing architecture.
4. Write the ticket following the standards below. Weave in project-specific details — reference real page names, existing components, and established terminology rather than generic placeholders.
5. Deliver the story using the configured output mode.
6. If the story covers more than one distinct user goal, ask whether to split it into multiple stories — large stories are harder to estimate and deliver incrementally.

Task — a concrete piece of work, often subordinate to a story. Clearly describe what needs to be done.

Bug — describes a deviation from expected behavior. Include steps to reproduce, actual result, expected result, and a link to the relevant page so it can be checked quickly.

Good titles: "Product Pages: Center Images Automatically", "Browser API: Update Custom Attribute Docs", "Distributed Tracing: Add CAT Relationship Detail".

• Independent — can be worked on without waiting for other tickets.
• Negotiable — leaves room for engineers to propose implementation approaches.
• Valuable — delivers clear user or business value.
• Estimable — contains enough detail for the team to size it.
• Small — represents a manageable unit of work (one sprint or less).
• Testable — a QA engineer or PM can verify the end result.

• Use everyday language. Say "the user sees a confirmation message" rather than "the component renders a toast notification."
• Describe behavior from the user's perspective: what they see, click, and experience — not what the system does internally.
• Avoid technical jargon: no API names, database terms, framework concepts, HTTP methods, or code-level vocabulary. If a technical concept is essential to the story, briefly explain it in plain terms (e.g. "real-time updates (the page refreshes automatically without reloading)").
• Keep sentences short and direct. Each acceptance criterion should be understandable on its own, without needing to re-read the rest of the story.

Use "Rules-oriented" criteria by default (a verification checklist). If the story involves complex multi-step flows, ask whether to switch to "Scenario-oriented" (Given/When/Then) format.

Writing style:

• Break requirements into specific, testable statements that a non-technical person can verify.
• Use present tense: "The field contains …" rather than "The field must contain …" — this reads as a description of the finished product.
• State default values, placeholder text, and labels explicitly — these are the details that get missed in implementation.
• Use action-oriented, user-facing language for buttons and labels (e.g. "Check Quality" rather than "Re-run").
• Describe behavior plainly instead of embedding concrete examples that need extra context to understand.
• Reference only features and data within the scope of this story. Use real page names, labels, and terminology discovered during the codebase exploration — generic placeholders make stories harder to implement.
• Keep the total number of acceptance criteria at or below 8. More than that usually signals the story should be split.
• File paths, function names, database models, or implementation details belong in dev notes or task comments, not in acceptance criteria.