/draft-story-markdown

name: Draft a story markdown from a story tracker or feature description
description: Generate a draft story markdown by analyzing a story tracker or feature description, Figma designs, and the codebase.
user-invocable: false

Draft a story markdown from a story tracker or feature description

Overview

This skill helps junior developers create technical story markdown by: 1. Gathering requirements from a story tracker or a provided feature description 2. Fetching Figma designs linked in the story (when applicable) 3. Exploring the codebase to discover relevant files and patterns 4. Generating a draft `story.md` for the developer to review and refine

Instructions

Phase 1: Gather Requirements

Option A: Ticket ID provided

When the input is a ticket ID (matching a pattern like `PROJ-123`, `86d2uf1mh`, `4821`, `AB#4821`). A bare integer is always a ticket ID, never a feature description:

• Use the project's story tracker MCP tools (Jira, ClickUp, Azure DevOps) to fetch the story by its ticket ID and download its attachments. If no story tracker MCP tool is available, tell the developer the project has no story tracker MCP server configured (`/mcp` to check status) and ask them to paste the story details or provide a feature description instead — never guess at the story content.
• Extract:
• Type (Story, Task, Bug/Defect, etc.)
• Summary (user story statement)
• Description (context and background)
• Acceptance criteria (requirements)
• Subtasks (if any)
• Figma links (URLs matching `figma.com/file/` or `figma.com/design/`)
• Steps to reproduce, actual and expected behaviour (bug tickets)
• Treat the ticket as a bug when its type is `Bug`, `Defect`, `Incident` or equivalent, or when it carries steps to reproduce with actual and expected behaviour.
• If the ticket is a bug, reproduce it before drafting. Follow its steps to reproduce by driving the app with `mcp__plugin_story-flow_playwright__*` tools, or `mcp__plugin_story-flow_appium__*` for a mobile app. Navigate relative to the base URL from `BASE_URL`, falling back to `use.baseURL` in the project's @playwright.config.js. Note the failing step, the actual behaviour and any console or network errors, and use them to inform the exploration keywords in Phase 2 and the tasks in Phase 3.
• If the bug does not reproduce, carry on drafting and highlight it as an assumption in Phase 4 for the developer to confirm the environment, version, account or seed data.
• If the fetch fails, inform the developer and ask them to verify:
• The ticket ID is correct
• The project's `.mcp.json` defines a story tracker MCP server, and they are logged into it (`/mcp` to check status)

Option B: Feature description provided

When the input is a feature description (not a ticket ID):

• Use the provided description as the basis for the story.
• Ask the developer clarifying questions if the description is too vague to derive requirements from, such as:
• What is the expected user flow?
• Are there specific acceptance criteria?
• Are there any Figma designs to reference?
• Derive a user story summary, context, and initial requirements from the description and any clarifications.

Phase 2: Explore Codebase

Use a **single comprehensive Explore agent** (Task tool with `subagent_type: Explore`) to discover:

1. **Project structure and conventions**

• Directory organization (e.g., `src/`, `components/`, `api/`, `schemas/`)
• File naming conventions (kebab-case, camelCase, PascalCase)
• Common patterns (how similar features are structured)

2. **Files related to the feature area**

• Search using keywords extracted from the story summary and description
• Look for existing files in the same domain/module
• Identify files that will likely need modification

3. **Similar existing implementations**

• Find reference patterns for the type of work (API endpoints, components, schemas)
• Note how tests are organized for similar features

4. **Technical conventions**

• Schema definitions and validation patterns
• API route patterns and middleware usage
• Component structure and state management approach

5. **Existing utility/helper patterns**

• Locate utility or helper directories (e.g., `src/utils/`, `src/helpers/`, `lib/`)
• Note naming conventions for shared modules
• Identify reusable functions that already exist (validation, formatting, transformations)
• Look for patterns where multiple modules import from the same shared location

**Exploration prompt template:**

Explore the codebase to help draft a story for: [SUMMARY FROM STORY TRACKER OR FEATURE DESCRIPTION]

Find:
1. Project structure - how are features organized?
2. Files related to: [KEYWORDS FROM REQUIREMENTS]
3. Similar implementations to use as reference patterns
4. Naming conventions for schemas, components, APIs, and tests
5. Where new files should be created based on existing patterns
6. Utility/helper directories and existing shared functions (validation, formatting, etc.)

Provide specific file paths and patterns discovered.

Phase 3: Generate Draft

**Important:** Do not include unit test requirements or tasks in the story. Unit tests are automatically created during implementation with 100% coverage for every source file. Only include QA tasks for BDD scenario planning and for verifying the implementation against the acceptance criteria.

Create a story markdown with the following structure:

[User story summary from the story tracker or feature description]

## Requirements

- [Requirement 1 from acceptance criteria or feature description]
- [Requirement 2 from acceptance criteria or feature description]
- [Additional requirements derived from Figma design]

## Tasks

- Use qa-tester subagent to plan BDD scenarios @path/to/feature.feature.
- Use backend-developer subagent to [task description] @path/to/file.js. [Technical details].
- Use frontend-developer subagent to [task desc