backlog-workflow

Backlog Workflow Skill

A skill for improving Story quality through structured refinement, readiness analysis, and codebase-aware technical enrichment. Integrates with GitHub via the gh CLI to read and comment on Story issues.

Usage

/backlog-workflow <command> [issue-number] [extra-args...]

Examples:

• /backlog-workflow improve 242
• /backlog-workflow improve 242 "Team decided to limit scope to admin users only, defer SSO"
• /backlog-workflow analyze 242
• /backlog-workflow refine 242
• /backlog-workflow enrich 242

Argument Parsing

Parse $ARGUMENTS to extract the command and its arguments:

• First token (required): The command name — one of improve, analyze, refine, enrich.
• Second token (required): The GitHub issue number (the Story's #N, with or without the leading #).
• 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.

Deprecated token — groom: If the first token is groom, do not route. Surface this warning verbatim and stop, so the user re-invokes with the new name:

⚠️ The groom command has been renamed to enrich. Please re-run as: /backlog-workflow enrich <issue-number>

The term "grooming" was retired due to its connotations in modern Agile usage; the command's behaviour is unchanged.

Command Routing

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

Command	File	Requires Issue Number
improve	commands/improve.md	Yes
analyze	commands/analyze.md	Yes
refine	commands/refine.md	Yes
enrich	commands/enrich.md	Yes

Read the command file and follow its instructions. Pass the issue number and any extra arguments to the command.

Validation before routing:

1. If no issue number was provided, ask for it — do not proceed without one.
2. Resolve the GitHub org/repo from .claude/context/platform-context.md (the Org + Repo fields, recorded by /init-workspace). Never hardcode an owner/repo. If platform-context.md is missing, halt with: "Workspace not initialized — run /init-workspace first." When running gh inside the repo clone, gh auto-detects the repo; otherwise pass --repo <org>/<repo>. Pass the resolved org/repo to the routed command.

Prerequisites

• gh CLI available and authenticated (gh auth status)
• The configured repo cloned locally (for enrich command)
• Run /init-workspace before using backlog commands (one-time setup)

Templates

Backlog 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/platform-context.md — single context file with sections:
  • Repo — local path, purpose, stack, surfaces, integration branch, worktree mode
  • GitHub Configuration — Org, Repo, Project (v2) number, Status/Surface field vocabulary, branch names, user slug (recorded by /init-workspace)
  • Repo-Specific Conventions — team coding patterns supplementing the canonical dotnet-conventions / react-turbo-conventions / expo-mobile-conventions skills