/backlog-generator

name: backlog-generator
description: "Turn existing audit findings into sprint-ready tickets with T-shirt estimates, acceptance criteria, dependencies and phases. Triggers: tickets from audit, backlog from findings, sprint planning from report. Not for the contribution process (contribution-workflow)."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(ls:*)
references:
  - ../../knowledge-notes/component-governance.md
  - ../../knowledge-notes/output-discipline.md

Backlog Generator

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

Context

The gap between "here are the problems" and "here is the plan for the next eight weeks" is where most audit value dies. Findings get filed, not acted on. Teams read the audit, nod, then move on because the step from "TA-07: Button component tokens not aliased correctly" to "what do we build next sprint?" is too large.

This skill bridges that gap by transforming audit output into structured work items that engineers and product managers can prioritise, estimate, and execute without needing to re-read the audit or negotiate what "fix the tokens" means. The output is sprints, not a wall of problems.

Boundaries

This skill transforms existing audit findings into work items. It does not run audits itself — if no audit output exists, run the relevant audit skill first. If the audit produced zero findings, there is no backlog to generate; confirm this with the user and stop. If the findings lack severity ratings or remediation guidance, flag the gap and produce work items with what is available, but note the missing context.

---

Steps

1. Accept and Parse Input

Accept input in any form: copy-paste audit report, file path, reference to prior audit skill output, or natural language description of findings.

Parse findings and extract:

• Finding ID (e.g., TA-01, COL-03)
• Severity: Critical, High, Medium, Low
• Category: Token structure, component API, documentation, tooling, process
• Current state: the problem as written in the audit
• Remediation: what the audit says should happen

Do not assume findings are complete. If a finding is vague ("tokens are broken"), ask clarifying questions before proceeding.

Also ask for team size and sprint length (and, if they have one, the capacity they can give system work per sprint). Phases in step 4 are sized against these; without them, group by dependency and priority only and say the phases aren't capacity-checked.

Ask how the team sizes work. If they use story points, or their own T-shirt definitions, use theirs and say so; the scale in step 3 is the default for teams that don't have one. A backlog in a foreign sizing scale gets re-estimated in the planning meeting, which wastes the estimate.

2. Classify Work Item Type

For each finding, assign one of these work item types:

• **Bug fix:** Something is broken and prevents correct usage (e.g., token alias creates circular reference, component prop ignored in doc site)
• **Tech debt:** Working-as-designed but the design itself is unsustainable (e.g., token hierarchy is flat, component prop not typed)
• **Enhancement:** New capability that enables better practice (e.g., new token tier, new component variant)
• **Migration:** Moving from one system to another (e.g., migrating component token refs from old to new tier)
• **Documentation:** Clarifying existing behaviour or adding examples

Document your reasoning for each classification. Different teams prioritise differently — tech debt might be lower priority than bugs, and that's a decision, not a mistake.

3. Generate Structured Work Item

For each finding, produce a work item with all of these fields:

**Title:** Action-oriented, engineer-readable. Prefer "Route component tokens through semantic tier" over "Fix TA-01" or "Token aliasing issue". The title should be understandable without the audit context.

**Type:** Bug fix, tech debt, enhancement, migration, or documentation (from step 2).

**Effort estimate:** in the team's own scale (step 1), or this default T-shirt scale with sizing rationale:

• S: under half a day (single-file change, tests included, no API review needed)
• M: half a day to two days (multi-file work, API implications, needs review)
• L: three days to a week (multi-component impact, a migration step, cross-team coordination)
• XL: more than a week (system-wide change, a major migration, new tooling); split it, or mark it for a scoping spike

Design system work is rarely three days when it crosses components or consumers, so the upper sizes run longer than a generic app scale.

Include 2–3 sentences of sizing rationale (e.g., "M because the Button component changes are isolated to one file, but we need to update three variants and test accessibility scenarios"). Do not estimate from severity — a critical bug might be 30 minutes (S) if it's a one-line fix.

**Acceptance criteria:** 2–4 testable statements. Each should be verifiable by a reviewer without ambiguity.

• Good: "No component token directly references a primitive token (checked via regex in token definitions)"
• Bad: "Fix tier leakage" or "Make tokens work better"

**Evidence:** the finding id and the audit's evidence for it (the file and line, token path or component it names), copied from the audit so the ticket stands without the report.

**Rationale:** 1–2 sentences explaining why this work matters to the system and team, not just a technical description. Address: Wh