Skip to content
Skills Library
Management & product · Planning

plan-backlog

/plan-backlog

Turn an idea or description (in any format) into a well-formed backlog — epics, user stories with acceptance criteria, sub-tasks — and create it in the team's tracker after approval. Elaborates progressively (guided, the default) or in one shot (`--quick`). Supports Jira, Linear, GitHub Issues, and Azure DevOps via adapters. Use when a product owner wants to draft or create tickets from an idea, brief, or document.

Author
theam ↗
Licence
Apache-2.0
Last repository change
28.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 28.09.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Turn an idea or description (in any format) into a well-formed backlog — epics, user stories with acceptance criteria, sub-tasks — and create it in the team's tracker after approval. Elaborates progressively (guided, the default) or in one shot (`--quick`). Supports Jira, Linear, GitHub Issues, and Azure DevOps via adapters. Use when a product owner wants to draft or create tickets from an idea, brief, or document.

Original author description

Turn an idea or description (in any format) into a well-formed backlog — epics, user stories with acceptance criteria, sub-tasks — and create it in the team's tracker after approval. Elaborates progressively (guided, the default) or in one shot (`--quick`). Supports Jira, Linear, GitHub Issues, and Azure DevOps via adapters. Use when a product owner wants to draft or create tickets from an idea, brief, or document.

How it works

  1. Trigger
  2. Project configuration
  3. 1. Intake — read the idea in whatever form it arrives
  4. 2. Discovery-first — learn the team's hierarchy and conventions
  5. 3. Choose the mode — guided by default
  6. 4. Draft the backlog
  7. 5. Review & approval gate (mandatory — create nothing yet)
  8. 6. Create — via the tracker's write adapter
  9. Authentication
  10. 7. Handoff
Original SKILL.md headings · 129 lines, 1,727 words
SKILL.md preview
---
name: plan-backlog
description: Turn an idea or description (in any format) into a well-formed backlog — epics, user stories with acceptance criteria, sub-tasks — and create it in the team's tracker after approval. Elaborates progressively (guided, the default) or in one shot (`--quick`). Supports Jira, Linear, GitHub Issues, and Azure DevOps via adapters. Use when a product owner wants to draft or create tickets from an idea, brief, or document.
---

# Plan Backlog

Turn a product idea into a structured, well-formed backlog in the team's tracker — the **upstream** half of the issue-to-PR workflow, for the product-owner persona. It closes the loop **idea → backlog → ticket → PR** (created stories feed straight into `work-story`).

This is the *write* counterpart to `issue-fetch` (which reads). **Nothing is created until you approve the draft.** You **facilitate** the PO's thinking — offer options and ask for decisions; never decide the product for them.

## Trigger

A request to turn an idea / brief / description / document into tickets, epics, or a backlog — e.g. *"draft stories for this feature"*, *"create Jira tickets from this doc"*, *"break this initiative into a backlog"*.

## Project configuration

Read `.claude/dev-kit.json` at the consuming repo root. The `tracker` block names the active adapter and its settings:

```json
{ "tracker": { "type": "jira" | "linear" | "github" | "azure", ... } }
```

**If the file does not exist (or has no `tracker` block), run `dev-kit-setup` first** — it detects the tracker and persists the config, then returns here. Don't ask for values setup can discover.

## 1. Intake — read the idea in whatever form it arrives

- **Pasted text / chat description** → use directly.
- **PDF** → read it (page range as needed).
- **Word (`.docx`)** → not natively readable; convert first (`textutil -convert txt file.docx -output -` on macOS, or `pandoc file.docx -t markdown`), then read. If neither tool is available, ask the user to paste the text or export a PDF.
- **Artifact / Confluence page / URL** → fetch it.
- **Figma link** (`figma.com/(design|file)/…`) → run `figma-fetch` for design context.
- **A `plan-definition` product definition** — passed in chat, or a `docs/definitions/<slug>.md` file → read it as the source. It carries the framing already (problem, users, goals/non-goals, metrics, chosen direction), which is what triggers the **lighter framing** in §4a. Check its provenance markers / "not established" / `[unverified]` notes: a definition that flags core gaps is **not** ready for the light path (see §4a).

Work only from what the source says plus what the user confirms — **never invent scope or acceptance criteria.**

## 2. Discovery-first — learn the team's hierarchy and conventions

Don't impose a structure; **mirror the team's.** Using the adapter for `tracker.type`, discover:

- the **issue types available and their hierarchy** (Epic / Story / Task / Feature / Sub-task, …),
- the **fields that matter** (acceptance criteria, story points/estimate, epic/parent link, labels, components),
- a **sample of recent issues** to calibrate granularity and writing style.

Ask only what can't be discovered.

## 3. Choose the mode — guided by default

Two modes; **decide per invocation, never persist a mode** — a mature project can still hold a brand-new feature, so there are **two maturities: the project's and the feature's**. Judge each run.

- **Guided (default):** elaborate progressively, zoom-out → zoom-in, offering alternatives and asking for a decision at each level (§4). This is the right default; it keeps the PO doing the *definition* work instead of handing every decision to the agent.
- **Quick (`--quick`):** produce the whole backlog in one draft (§4, Quick). An explicit opt-in for when the PO just wants a fast draft.

**Signals for how much guidance a run needs** (discovery-first, never assumed):
- **Repo docs:** an empty/greenfield repo vs. one with a defined stack, conventions, and `CLAUDE.md` — the emptier it is, the more definition help the framing step should give.
- **Brief context:** how much useful context the idea/brief already carries.

Even on a mature project, still do a **light framing check** (§4a) — don't skip framing on the assumption it isn't needed. If the mode is genuinely ambiguous, **ask once**.

## 4. Draft the backlog

### Guided mode (default) — zoom-out → zoom-in

Move through **three levels**; at each, present **2–4 alternatives** (as many as the situation needs, no padding), recommend one with a reason, and **wait for the PO's decision** before going deeper. Ground every option in the intake + discovery — never fabricate.

**4a. Framing (zoom-out) — help *define*, not just structure.** Restate the goal and map the problem space (users, outcomes, constraints, unknowns). Offer 2–4 **framing alternatives** — e.g. MVP vs. full, different ways to slice the initiative, different sequencing — with the trade-offs of each. → PO chooses the framing.

> **If a `plan-definition` product definition was handed in** (problem statement, users, goals/non-goals, metrics, chosen direction), the problem is already framed — *if it's grounded.* Before taking the light path, **check the definition, not just its headings**: a doc whose core must-haves are "not established", or whose thesis rests on `[unverified]` claims, is a spark with a template around it — treat it as an ordinary idea and frame from scratch (§4a). Only when the definition is genuinely grounded, run a **lighter framing**: *confirm* its direction and slice from it rather than re-deriving. Also re-open framing if the definition leaves the backlog-relevant slicing undecided. The presence of the five sections is not the signal; their groundedness is.

**4b. Epics / themes.** For the chosen framing, propose the epics/themes with **alternatives** where the breakdown could reasonably differ. → PO adjusts.

**4c. Stories.** Within each chosen epic, propose user stories (*"As a `<role>`, I want `<capability>`, so that `<value>`"*) with Given/When/Then **acceptance criteria**, INVEST-sized, offering **scoping alternatives** (split/merge, in/out) where it matters. → PO refines.

Then assemble the full draft and go to the approval gate (§5).

### Quick mode (`--quick`) — one-shot draft

Work with a neutral backlog model and produce the whole thing at once:

- **Initiative / Epic** → the outcome / theme.
- **User Story** → *"As a `<role>`, I want `<capability>`, so that `<value>`."* with Given/When/Then **acceptance criteria**, **INVEST**-sized.
- **Sub-tasks** → concrete steps, when they add clarity.
- **Dependencies**, sizing hints, labels/components, and explicit **out-of-scope** notes.

Recommend a shape based on discovery and **confirm it** with the user — don't force one. Then go to the approval gate (§5).

## 5. Review & approval gate (mandatory — create nothing yet)

Present the **full assembled draft**: the hierarchy plus each item's title, description, acceptance criteria, labels, and links. **Wait for explicit approval**; the user may edit anything. Only after approval proceed to create. (Same doctrine as `work-story`'s plan gate — never create tickets without a human OK. In guided mode the per-level decisions do not replace this final gate.)

**Rich review surface (when the host supports artifacts — e.g. Claude Code / claude.ai).** For anything beyond a couple of items, also render the draft as a **navigable artifact** so a large backlog is easy to scan and drill into — collapsible **epics → stories**, each showing its user story, Given/When/Then acceptance criteria, labels, sizing, and dependencies; with search/filter and a table-of-contents. Load the `artifact-design` skill before building it. The artifact is a *review aid, not the gate itself*: still print a concise hierarchy summary and ask for approval **in the conversation** (a page or dialog is not a substitute — the user must be able to approve in the chat). On hosts without artifacts (Codex / Cursor / Copilot), present the draft as Markdown.

## 6. Create — via the tracker's write adapter

Create **parents before children**, link children to parents, and set labels/components/points where discovered. Report each created item with its key/URL.

### Jira (`type: "jira"`) — Atlassian MCP
Config: `site`, `cloudId`, `projectKey`, `fields`.
- Discover types/fields with `getJiraProjectIssueTypesMetadata` / `getJiraIssueTypeMetaWithFields`.
- Create with `createJiraIssue` (project, issue type, summary, description, the acceptance-criteria field, labels, story points). Link stories to the epic via the epic-link field or `createIssueLink`; model dependencies with `createIssueLink` (Blocks / Relates).

### Linear (`type: "linear"`) — Linear MCP
Config: `teamKey` (and optionally `workspace`).
- Create issues under the team; use a **Project** (or a parent issue) as the epic, and **sub-issues** for sub-tasks; set labels/estimate/state. Put acceptance criteria in the description (a checklist).

### GitHub Issues (`type: "github"`) — `gh`
Config: `repo` (`owner/name`; defaults to `origin`).
- `gh issue create --repo <owner/name> --title <t> --body-file - --label <type>` (use `--milestone` as the epic/initiative). Acceptance criteria as a task list in the body; sub-tasks as sub-issues / task lists.
- **Verify writes by read-back — never trust the exit code.** `gh issue edit`/label can fail while applying nothing on repos whose org ever used classic Projects. After creating/labelling, run `gh issue view <number> --json labels,milestone` and, on a miss, apply via REST (`gh api repos/<owner>/<repo>/issues/<number>/labels -f "labels[]=<label>"`).

### Azure DevOps (`type: "azure"`) — Azure DevOps MCP / `az boards`
Config: `org`, `project`.
- `az boards work-item create --type "Epic|Feature|User Story|Task" --title <t> --fields ...`; link parent/child with `az boards work-item relation add`. Acceptance criteria → `Microsoft.VSTS.Common.AcceptanceCriteria`.

## Authentication

If the adapter's backend is not authenticated (MCP connector not authorized, `gh`/`az` not logged in), tell the user exactly how to authenticate — MCP connectors via `/mcp` or claude.ai connector settings; CLIs via `gh auth login` / `az login` — and stop. **Never create partial or placeholder items.**

## 7. Handoff

List the created items with their keys/URLs and hand off: each story is worked by running **`work-story <KEY>`** on it — one **interactive** session per story (the plan is approved in the chat, then it implements and opens the PR); `launch-story` opens a window per story to run several in parallel. That completes the loop **idea → backlog → ticket → PR**.

**Don't invent a way to "build the backlog" automatically.** The kit has no batch/async, CI, comment, label, or assignment trigger, and ships no workflow runner — never propose or scaffold one (no `/builder` comments, no `codex-builder.yml`). If the repo already has its *own* async coding agent (a real `.github/workflows` file, or GitHub Copilot's coding agent), you may point the user to its actual trigger **after verifying it exists** — never a fabricated one.

## Guardrails

- **Never create anything before explicit approval.**
- **Facilitate, don't decide:** offer alternatives and ask for the PO's decision at each level — don't hand them a finished product and call it done.
- **Discovery-first:** mirror the team's hierarchy and conventions; don't impose one.
- **Don't fabricate** scope or acceptance criteria — ground everything in the source plus user confirmation.
- Watch for **secrets/PII** in the source material; don't copy them into tickets.
- On partial failure, report exactly what was created and what wasn't — never leave a half-built backlog unreported.

Versions

The database has no other skills named plan-backlog.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version a7465fc03a07 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90using-tracker
    Use when the user mentions issues, tickets, tasks, epics, current work, sprint or cycle, backlog, creating or updating issues, or anything about task tracking and planning in any tracker (Linear, Jira, GitHub Issues, local files). Invoke BEFORE asking the user any question about…
  • 100issue-fetch
    Fetch a work item (summary, status, description, acceptance criteria, comments) from the team's issue tracker and display a clean summary. Supports Jira, Linear, GitHub Issues, and Azure DevOps via adapters. Use whenever a prompt contains an issue reference (e.g. PROJ-1234,…
  • 100backlog-plan
    Read-only backlog planning for Azure DevOps, GitHub, and Jira. Use to discover, triage, sprint-plan, or resume without mutating a tracker.
  • 90task-ledger
    Use when turning a plan into trackable tasks and working them to done — a lightweight issue tracker for an orchestrated run. Covers the task format (acceptance criteria, status, dependencies, assigned agent + model) and three backends: local markdown files (default), GitHub…
  • 100om-backlog
    Turns a product brief (its Scope and Key flows) or a spec's Phasing into a tracker backlog — epics, stories with acceptance criteria, tasks — with stable ids in titles, epic checklists, and Epic links, filing every issue through om-prepare-issue so dedupe, SDLC labels, and…
  • 90backlog-execute
    Mutating backlog execution for Azure DevOps, GitHub, and Jira. Use to create one item or apply a reviewed handoff to a confirmed tracker.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.