How do I specify which Jira ticket to audit?

Provide the Jira ticket ID (e.g., JIRA-2070); the skill fetches the complete story details including description, acceptance criteria, and subtasks.

What will the output include?

A findings report highlighting missing or mismatched requirements, misaligned tasks and assignments, technical accuracy checks, and a per-task implementation summary with a codebase verification checklist.

Can this be used after Jira updates?

Yes. Re-run the audit to ensure story.md remains aligned with the latest Jira requirements and subtasks, updating any discrepancies as needed.

Review a story markdown against a Jira story

npx machina-cli add skill Intai/story-flow/review-story-against-jira --openclaw

Files (1)

SKILL.md

2.3 KB

Review a story markdown against a Jira story

Instructions

Fetch the Jira issue by its ticket ID (e.g., JIRA-2070) to retrieve the complete story details including description, acceptance criteria, and subtasks.
Read the local story markdown file using the Read tool.
Compare the Jira story content against the markdown file and identify discrepancies.
Review the following aspects:
- Requirements Completeness: Verify all Jira acceptance criteria and requirements are documented in the markdown.
- Task Breakdown: Check that tasks in the markdown align with Jira story requirements and subtasks.
- Agent Assignments: Ensure tasks have appropriate agent assignments (Use backend-developer subagent to, Use frontend-developer subagent to, etc.).
- Technical Accuracy: Validate that the technical approach and implementation details match Jira specifications.
Report findings with specific examples of what's missing, incomplete, or misaligned.
Highlight any requirements from Jira that are not reflected in the markdown.
Note any tasks in the markdown that don't map to Jira requirements.
Task Implementation Summary: For each task in the markdown, provide a summary of what will be implemented:
- Describe the key changes, features, or components that will be built
- Codebase Verification:
  - For files to modify: Confirm they exist and identify relevant code sections
  - For new files: Verify target directories exist and check naming conventions against similar files
  - For dependencies: Check that referenced modules, components, or APIs exist
  - Identify similar existing implementations as reference patterns
- Implementability Assessment: Mark each task as:
  - ✅ Doable - Can be implemented as described
  - ⚠️ Needs Adjustment - Feasible with modifications (explain what)
  - ❌ Blocked - Cannot be implemented (list blockers)

Example Inputs

Review @path/to/story.md against Jira story JIRA-2070
Compare Jira issue JIRA-2070 with @path/to/story.md
Validate that @path/to/story.md matches the Jira requirements for JIRA-2070
Check if the story file matches JIRA-2070

Source

git clone https://github.com/Intai/story-flow/blob/main/plugins/story-flow/skills/review-story-against-jira/SKILL.mdView on GitHub

Overview

This skill fetches a Jira issue by its ticket ID, reads the local story markdown file, and compares them to verify that requirements, tasks, and assignments are aligned. It reports gaps, misalignments, and provides a task-by-task implementation summary aligned to Jira specifications.

How This Skill Works

The skill retrieves the Jira issue by ticket ID to obtain description, acceptance criteria, and subtasks. It then reads the local story.md using the Read tool and performs a structured comparison to ensure requirements are complete, tasks align with Jira, and agent assignments are correct (e.g., backend-developer, frontend-developer). It outputs a findings report with concrete examples of omissions or mismatches and a per-task implementation summary plus a codebase verification checklist.

When to Use It

When you need to ensure local story.md captures all Jira acceptance criteria and requirements
When validating that the markdown task breakdown maps to Jira story subtasks
When reviewing agent assignments to ensure appropriate roles are assigned (backend-developer, frontend-developer, etc.)
When verifying that technical approaches in story.md match Jira specifications
When preparing an implementation plan from Jira requirements to the story markdown

Quick Start

Step 1: Fetch Jira issue by ticket ID (e.g., JIRA-2070) to load description, acceptance criteria, and subtasks
Step 2: Read the local story.md file with the Read tool
Step 3: Run the comparison to generate a findings report and a per-task implementation summary with codebase verification

Best Practices

Always fetch and reference the Jira issue (description, acceptance criteria, subtasks) before reviewing the markdown
Verify every Jira acceptance criterion is documented in story.md with explicit coverage
Map markdown tasks to Jira subtasks and ensure assignments use the correct agent roles
Cross-check technical details in story.md against Jira specs for accuracy
Provide a clear, task-level implementation summary with codebase verification notes

Example Use Cases

Example: JIRA-2070 requires authentication flow; ensure story.md lists all ACs and backend/frontend tasks with proper assignments
Example: After Jira rework, use this skill to confirm story.md reflects updated acceptance criteria
Example: Detect mismatches where a markdown task exists but no corresponding Jira subtask is present
Example: Validate that all critical UI changes in Jira are broken into frontend tasks in story.md
Example: Identify Jira requirements not reflected in the markdown and propose additions

Frequently Asked Questions

Add this skill to your agents