---
name: story-workflow
description: >
  Refine, analyze, improve, and groom user stories / issues with structured templates and
  codebase-aware technical analysis. Supports ADO, Jira, GitLab, GitHub, and local markdown
  files as work item sources via provider adapters. Use this skill whenever the user mentions
  story refinement, story grooming, story analysis, story improvement, acceptance criteria,
  user story quality, sprint readiness, or commands like /story-improve, /story-refine,
  /story-analyze, or /story-groom. Also trigger when the user references work item or issue
  IDs (or local .md file paths) in the context of improving or reviewing story quality.
  This skill is never invoked autonomously — it only runs when explicitly requested by a human user.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent, mcp__azure-devops__*, mcp__jira__*, mcp__gitlab__*, mcp__github__*, mcp__zoho__*
argument-hint: "<command> [work-item-id-or-filepath]"
---

# Story Workflow Skill

A skill for improving user story / issue quality through structured refinement, readiness
analysis, and codebase-aware technical grooming. Integrates with the configured work item
provider (ADO, Jira, GitLab, GitHub, or local markdown file) via MCP or the filesystem
to read and post back to work items.

## Provider Resolution

Before executing any command, **read `.claude/context/provider-config.md`** to determine
the active work item provider. Then read the corresponding adapter from
`skills/providers/<provider>/work-items.md` for exact tool names, parameter mappings,
and field extraction logic.

**For `local-markdown`:** The work item ID is a file path (absolute or relative), not a
numeric or key-style ID. No MCP call is needed — use the `Read` tool directly on the path.
Verify the file exists before proceeding; if it does not, inform the user and stop.

## Usage

```
/story-workflow <command> [work-item-id] [extra-args...]
```

**Examples:**
- `/story-workflow improve 123456` (ADO)
- `/story-workflow improve PROJ-123` (Jira)
- `/story-workflow improve 42` (GitLab / GitHub)
- `/story-workflow improve 123456 "Team decided to limit scope to admin users only, defer integrations"`
- `/story-workflow improve ./stories/auth-story.md` (local-markdown)
- `/story-workflow analyze 123456`
- `/story-workflow analyze ./stories/auth-story.md` (local-markdown)
- `/story-workflow refine PROJ-123`
- `/story-workflow groom 42`
- `/story-workflow groom ./stories/auth-story.md` (local-markdown)

## Argument Parsing

Parse `$ARGUMENTS` to extract the command and its arguments:

- **First token** (required): The command name — one of `improve`, `analyze`, `refine`, `groom`.
- **Second token** (required): The Work Item / Issue ID (format depends on provider).
- **Remaining tokens**: Passed through as extra arguments (e.g., session notes for `improve` or `refine`).

If the first token is missing or doesn't match a known command, show the usage line above
and list the four commands with one-line descriptions. Do not guess.

## Command Routing

Route to the matching command file based on the first token:

| Command | File | Requires Work Item ID |
|---------|------|-----------------------|
| `improve` | `commands/improve.md` | Yes |
| `analyze` | `commands/analyze.md` | Yes |
| `refine` | `commands/refine.md` | Yes |
| `groom` | `commands/groom.md` | Yes |

Read the command file and follow its instructions. Pass the work item ID and any extra
arguments to the command.

**Validation before routing:**
1. If no work item ID was provided, ask for it — do not proceed without one.
2. Check that `.claude/context/provider-config.md` exists. If missing, remind the user to run `/init-workspace` first.
3. For `local-markdown`: verify the file at the given path exists and is readable. If not, report the resolved absolute path and stop.

## Prerequisites

- Work item provider MCP tools available (as configured in `provider-config.md`)
- Team repos cloned locally (for `groom` command)
- Run `/init-workspace` before using story commands (one-time setup)

## Templates

Story templates and output formats live in `templates/`. Commands reference them as needed.
Do not modify templates during command execution.

## Context Files

Generated by the standalone `/init-workspace` skill. Each developer generates their own
set by running `/init-workspace`. Files live at `.claude/context/` (git-ignored):

- `.claude/context/provider-config.md` — Provider settings, tool mappings, and field mappings.
- `.claude/context/repos-metadata.md` — Describes each repo's purpose, stack, and domain.
- `.claude/context/repos-paths.md` — Maps repo names to local filesystem paths.
- `.claude/context/conventions.md` — Team coding patterns and architectural conventions.