| name | spec-to-backlog |
| description | Convert a specification into a reviewed Jira epic and backlog with atl. USE WHEN decomposing requirements, RFCs, or designs into linked Jira work. DO NOT USE WHEN the source is meeting notes, only a summary is wanted, or the task is a direct service operation. |
Spec → backlog with atl
Read the spec → propose a breakdown → get approval → create the Epic
first, then children linked to it. link-epic needs the Epic to already
exist, so create it first and capture its key. Never create anything before
the user approves the breakdown. Command details live in the jira and confluence
skills.
Preflight: atl must be installed and configured. If command -v atl fails
or a command exits 7 ("not configured"), run $setup and stop.
Workflow
1. Fetch the spec
export ATL_READ_ONLY=1
atl conf page view <id> -o text
atl conf pull --id <id> --into <dir>
For a long or multi-section spec, use the second command and read the generated
.md.
Ask for the target Jira project key if not given, and confirm the instance's
issue types before planning (a failed issue create names the valid types;
many instances lack "Story").
2. Analyze and propose — no writes
Break the spec into 5–15 tickets. A good ticket is independently deliverable,
roughly 1–5 days of work, and testable. Split along architectural layers or
user-facing capabilities; add cross-cutting tickets (migration, docs, rollout)
only where the spec implies them.
Present: the proposed Epic name, a table of ticket summaries with type and
rough scope, and — explicitly — anything in the spec you chose not to turn
into a ticket. Wait for approval or edits.
3. Create the Epic first
atl jira issue create --project KEY --type Epic --summary '<epic name>' --from-md epic.md
Epic description: one-paragraph goal, a link back to the spec page, success
criteria. Capture the returned key — every child needs it.
4. Create children, link each to the Epic
Per ticket, sequentially (so a failure can't silently orphan half the batch):
atl jira issue create --project KEY --type Task --summary '<verb-first title>' --from-md t1.md
atl jira issue link-epic KEY-101 --epic KEY-100
Ticket description template: Context (1–2 sentences + spec section) / Scope /
Acceptance criteria (checklist) / Out of scope. Titles start with a verb:
"Add…", "Migrate…", "Expose…".
If a create fails mid-run: stop, report every key created so far, and ask
how to proceed. atl never retries POSTs (no double-create risk) — do not
retry blindly yourself either.
5. Summarize
Table of Epic + child keys/summaries, plus the source page id. Offer
follow-ups without performing them: assignees
(atl jira user search '<name>' → --field 'assignee={"name":"…"}' via
issue update), sprint placement (atl jira sprint add), priorities.
Pitfalls
| Symptom | Cause / fix |
|---|
exit 8 on --from-md | unconvertible markdown block — the error names it; keep bodies to plain headings/lists/fences |
link-epic fails | Epic Link is a custom field on some Server/DC instances; report the error and suggest linking manually rather than guessing field ids |
| type rejected | verify types once before the batch, not per ticket |
