Draft a story markdown from a story tracker or feature description

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
2. Directory organization (e.g., src/, components/, api/, schemas/)
3. File naming conventions (kebab-case, camelCase, PascalCase)
4. Common patterns (how similar features are structured)

1. Files related to the feature area
2. Search using keywords extracted from the story summary and description
3. Look for existing files in the same domain/module
4. Identify files that will likely need modification

1. Similar existing implementations
2. Find reference patterns for the type of work (API endpoints, components, schemas)
3. Note how tests are organized for similar features

1. Technical conventions
2. Schema definitions and validation patterns
3. API route patterns and middleware usage
4. Component structure and state management approach

1. Existing utility/helper patterns
2. Locate utility or helper directories (e.g., src/utils/, src/helpers/, lib/)
3. Note naming conventions for shared modules
4. Identify reusable functions that already exist (validation, formatting, transformations)
5. 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 backend-developer subagent to [task description] @path/to/file.js. [Technical details].
- Use frontend-developer subagent to [task description] @path/to/component.jsx. [Technical details].
- Use qa-tester subagent to plan BDD scenarios @path/to/feature.feature.
- Use qa-tester subagent to verify the implementation meets the acceptance criteria by executing all BDD scenarios @path/to/feature.feature via the /execute-scenario command. If any scenario fails, fix the implementation with the appropriate developer subagent and re-run until every scenario passes.

Task guidelines:

• Each task should have:
• Agent assignment (Use backend-developer subagent to, Use frontend-developer subagent to, Use mobile-developer subagent to, Use qa-tester subagent to)
• Clear action description
• Specific file path(s) using @path/to/file format
• Technical details about what to implement
• Relevant Figma links for reference, if available
• Group related work into single tasks when appropriate
• Always include a QA task to plan BDD scenarios
• Always include a final QA task to verify the implementation by executing the BDD scenarios (via /execute-scenario) and fixing any failure until all scenarios pass
• Use existing file paths discovered during exploration
• For new files, follow the naming conventions discovered
• Shared utility tasks: When exploration reveals that two or more tasks will need the same logic (validation, formatting, data transformation), add a separate task to create the shared utility function before the tasks that use it. This avoids duplicating logic across tasks and keeps each task focused on a single responsibility.
• Only create utility tasks when the shared pattern is genuinely identical across consumers — do not pre-emptively abstract similar-looking code that may diverge.
• Place utility files in the project's existing utility directory (discovered during exploration, e.g., src/utils/, src/helpers/).
• Name utility files by category (e.g., validation.js, formatting.js, transforms.js), not one function per file.
• IMPORTANT: Do NOT add task dependency or ordering annotations (e.g. "Parallel tasks 1-3:", "Sequential task N after task M completes:"). List tasks as unordered bullet points in any logical order. Task dependencies and parallel execution grouping are handled separately using the analyze-task-dependencies skill after the st