Imported from sean-m-cooper/ai_tools (skills/story-writer/SKILL.md). Install upstream with npx skills add sean-m-cooper/ai_tools --skill story-writer. Copyright stays with the author.

Story Writer

Overview

Interactive guided interview for writing high-quality work items. Collects all required information through conversation, produces a structured document, and optionally creates the item in a tracking system (Jira or Azure DevOps).

Announce at start: "I'm using the story-writer skill to help you create a quality work item."

Handling Pre-Populated Briefs

Check $ARGUMENTS for a story brief (passed from story-splitter) and/or a TRACKING SYSTEM block.

If a brief is present, extract what's already provided and skip or pre-fill the corresponding interview questions:

For any field not in the brief, ask the question as normal.

When running standalone (no brief), run the full interview from Step 1.

Step 1 — Detect Issue Type

Ask:

"Are we writing a Story, Bug, or Task?"

Then determine the story scope:

• Story (UI or vertical slice) -> run the UI/Vertical Slice Interview (Step 2A)
• Story (backend-only, no UI) -> run the Backend Interview (Step 2C)
• Bug -> run the Bug Interview (Step 2B)
• Task -> run the Task Interview (abbreviated Step 2A — skip Q4 CRUD, Q5 inputs, Q6 validation, Q7 feedback)

How to determine scope: If the brief includes a Story Scope: Backend field, use Step 2C. If the PO says "Story", ask: "Does this story involve UI changes, or is it a backend-only change (API, service, data pipeline, infrastructure)?" UI or vertical slice -> Step 2A. Backend-only -> Step 2C.

Step 2A — Story / Feature / Task Interview

Ask each question one at a time. Wait for the answer before asking the next. Do not batch questions.

Q1 — Component / Area

"Which component(s) or area(s) of the product does this affect?"

Q2 — Title (Summary)

"Write the story title. A good title completes the sentence: 'After this story, the [persona] will be able to...' — state the deliverable, not the task steps.

Good: 'Flagging a message for SMS responses when a user creates a new template' Bad: 'Change navigation order and rename My Business Rules to My BRs'"

Q3 — Description

"Describe the user journey. Include: who is the persona (admin, member, guest, etc.), what they see, and what they do. Start with 'As a [persona]...' and describe the experience from the user's perspective — not the database schema or code changes."

Q4 — CRUD Verb (skip for Task type)

"What is the primary CRUD verb for this story?

• Create — user adds something new
• Read — user views or lists something
• Update — user edits something existing
• Delete — user removes something

If more than one applies, we should consider splitting the story."

Q5 — UI Elements / Inputs (skip for Task type)

"What input fields, buttons, or UI elements are involved? For each input, what is its data type? (text, number, date, dropdown, checkbox, image, etc.)"

Q6 — Validation Rules (skip for Task and Read types)

"For each input field, what validation rules apply?

• What makes it invalid?
• What error message should appear?
• Does a failed validation block the action (prevent save/navigation)?
• Are there any format masks? (phone, zip, date, etc.)"

Q7 — User Feedback (skip for Task and Read types)

"What feedback does the user receive after completing the action? For example: success toast, confirmation modal, redirect to another page. Please specify the exact message text if possible."

Q8 — Acceptance Criteria

"Let's write the Acceptance Criteria. Based on your answers, here's a draft — review and expand it:

[Generate a numbered draft AC from all prior answers. Group with sub-points. Cover Screen Events, UI Definition, User Actions, User Feedback, and Validation as applicable to the CRUD verb.]

Make sure each criterion is numbered and specific. Avoid vague statements like 'data is saved correctly' — specify the exact field, value, and outcome."

Q9 — Technical Details (optional)

"Are there any technical details developers should know? For example: API endpoints to call, data model changes, third-party integrations, known constraints, or performance considerations. Skip if none."

Q10 — Priority

"What priority should this be assigned? Blocker / High / Medium (default) / Low / Lowest"

Q11 — Parent (optional)

"Is this a child of an existing Feature or Epic? If so, provide the work item key or ID. Otherwise, skip."

Step 2B — Bug Interview

Ask each question one at a time. Do not batch questions.

Q1 — Component / Area

"Which component(s) or area(s) of the product is this bug in?"

Q2 — Title (Summary)

"Write the bug title. A good title names the broken behavior AND the affected area.

Good: 'Payment form does not validate expiration date on submit' Bad: 'Payment not working'"

Q3 — Steps to Reproduce

"Provide numbered steps to reproduce the bug. Be specific enough that someone unfamiliar with the feature can follow them from scratch."

Q4 — Expected Behavior

"What should happen — what is the correct behavior?"

Q5 — Actual Behavior

"What actually happens — what is the broken behavior?"

Q6 — Environment

"Provide environment context:

• Browser and version
• Operating system
• User role / account type
• Any relevant data context (e.g., specific feature flag state, contract status)"

Q7 — Acceptance Criteria

"What does 'fixed' look like? Write the acceptance criteria — what must be true for this bug to be considered resolved? Be specific, not just 'it works'."

Q8 — Technical Details (optional)

"Any technical details, error logs, console output, or stack traces that would help developers? Skip if none."

Q9 — Priority

"What priority? Blocker / High / Medium (default) / Low / Lowest"

Step 2C — Backend Story Interview

Use this path for stories that are purely backend — no UI component. Ask each question one at a time.

Q1 — Component / Area

"Which service(s) or area(s) of the system does this affect?"

Q2 — Title (Summary)

"Write the story title. A good title names the operation and resource — what the system will be able to do when this is done.

Good: 'Create order via REST API', 'Process payment.failed events from Stripe webhook' Bad: 'Update database schema', 'Backend work for orders'"

Q3 — Description

"Describe what this operation does and who/what consumes it. Start with 'This operation allows [consumer] to...' and describe the behavior from the caller's perspective — not the internal implementation."

Q4 — Operation Type

"What type of operation is this?

• API endpoint — a synchronous request/response operation
• Event handler — processes an async event
• Event publisher — emits an event for other services
• Scheduled job — runs on a schedule or trigger
• Data migration — one-time or versioned data transformation
• Integration — connects to an external system

If more than one applies, we should consider splitting the story."

Q5 — Request / Input Shape

"What data goes in? Describe the categories of input (e.g., 'customer details', 'order line items') and any required vs. optional fields at a high level. For APIs: what does the request look like?"

Q6 — Response / Output Shape

"What data comes out? Describe the response or output. For APIs: what does a successful response look like? What status codes are used?"

Q7 — Error Handling

"What are the error scenarios and how should each be handled?

• What makes a request invalid? (validation errors)
• What happens if a dependency is unavailable? (timeouts, retries, fallbacks)
• What error codes or messages should be returned?
• Are there idempotency requirements?"

Q8 — Acceptance Criteria

"Let's write the Acceptance Criteria. Based on your answers, here's a draft — review and expand it:

[Generate a numbered draft AC from all prior answers. Cover: operation behavior, input validation, success response, error responses, edge cases, and any non-functional requirements.]

Make sure each criterion is numbered and specific. Avoid vague statements like 'handles errors gracefully' — specify the exact error, response code, and behavior."

Q9 — Technical Details (optional)

"Any technical details developers should know? For example: auth requirements, rate limits, data model changes, migration steps, infrastructure dependencies, or performance constraints. Skip if none."

Q10 — Priority

"What priority should this be assigned? Blocker / High / Medium (default) / Low / Lowest"

Q11 — Parent (optional)

"Is this a child of an existing Feature or Epic? If so, provide the work item key or ID. Otherwise, skip."

Step 3 — Preview & Confirm

Before creating the work item, show a structured preview:

Issue Preview
---------------------------------------------
Type:         [Story / Bug / Task / Feature]
Summary:      [title]
Component(s): [component(s)]
Priority:     [priority]

Description:
[description text]

Acceptance Criteria:
[AC text]

Technical Details:
[tech details or "(none)"]
---------------------------------------------
Shall I create this work item? (yes / edit [section name] / cancel)

• yes -> proceed to Step 4
• edit [section name] -> re-ask the relevant question(s), then re-show the preview
• cancel -> stop and discard

Step 4 — Create the Work Item

If a TRACKING SYSTEM block was provided (from story-splitter or feature-writer), use it directly — do not re-ask the PO which system to use. Set the parent from the block if provided and Q11 was skipped.

If no tracking context was provided (standalone mode), ask:

"Would you like me to create this in a tracking system? If so, which one — Jira, Azure DevOps, or none (just keep the document)?"

Jira

Ask for the project key and cloud ID if not already known from the tracking context. Use the appropriate Jira MCP tool to create the issue with:

Azure DevOps

Ask for the organization and project name if not already known from the tracking context. Use the appropriate Azure DevOps MCP tool to create the work item with:

None

Present the final formatted document for the PO to copy into their system manually.

Description format for Bugs

Construct from interview answers:

*Steps to Reproduce:*
1. [step]
2. [step]

*Expected Behavior:*
[expected]

*Actual Behavior:*
[actual]

*Environment:*
- Browser: [browser]
- OS: [OS]
- User Role: [role]
- Context: [context]

Step 5 — Confirm & Review

After the work item is created (or document delivered):

1. Output confirmation:

   "Created [work item ID] — [title]"

2. If the incoming brief contained PREFINEMENT: defer (story-writer was invoked by story-splitter as part of a batch), skip the prefinement offer — the splitter runs a single batch review over all stories at the end. Just return after confirmation.

   Otherwise (run standalone), ask: "Would you like me to run a quality review on this work item?"

   If yes, invoke the story-prefinement skill, passing the work item details and the TRACKING SYSTEM block if available.

Common Mistakes to Prevent