---
name: backlog-import-plan
description: Turn an agreed specification (a .devbook/domain feature, an ADR, or other planning material) into a Backlog import plan — an ordered, dependency-linked sequence of entries in Backlog's entry-text grammar, ready to paste or upload — together with a review view of it, always.
disable-model-invocation: true
---

# Build a Backlog import plan

Open the reply with `backlog-tools@<version>`, `version` read from `../../.claude-plugin/plugin.json`, not recalled.

A one-shot handoff: the spec is settled and it is time to generate the next batch of AI
prompts for the Backlog app to import. This skill reads the agreed material, writes one
Backlog import plan document plus a review view of it, and stops — it never talks to the
Backlog app, executes a generated prompt, or touches GitHub.

Read `assets/backlog-import-grammar.md` before writing anything. It carries the exact
entry/sub-item shape, every metadata token and its values, and the plan-identity/re-import
mechanics; use only the syntax it defines.

## Inputs

- **Source material.** Path(s) to the agreed `.devbook/domain` feature chapter, an
  ADR, or — if nothing is written down yet — the planning notes given inline.
- **Plan subject.** What the batch delivers; derives the shared `+tag`.
- **Target repositories.** One or more repository names the prompts target. Do not check
  whether a name is already registered in Backlog — Import auto-registers an unknown one.
- **Output.** A file path, or "paste it here" — ask if neither is stated. The review view
  (step 7) is produced either way; it is not an option.
- **Level.** Step-level (the default) or, when asked, [roadmap-level](#roadmap-level-mode).
- **The user's answers.** Gathered by the [interview](#interview) while the plan is written,
  never assumed.

## Prompts first

The user prefers work an AI session runs over work they do themselves, and wants every
question a step would raise answered while the plan is written, not when a step runs.
`prompt` is the default kind. A step is a `task` or `test` only when it is the closing
sign-off, or when the interview offered to hand it to an AI session and the user kept it.
A prompt runs to the end without asking anything the plan could have settled; the only
stops left in it are the gates the target repository's own process sets, such as its
approval before a pull request.

## Workflow

1. Read the source material in full, following any `depends-on`/prerequisite references it
   names, so ordering is grounded in what is agreed rather than guessed. Note each open
   question as you read: an unresolved decision, an alternative left open, a `TBD`, an
   `annotation` fence, a value the work needs but the source does not give.
   Then run the [interview](#interview)'s first round, before drafting any entry.
2. Derive the plan's `+tag`: one slug from the plan subject, written with the `+` sigil
   Backlog stores plan tags under (a `#slug` is a general tag and a different plan from
   the `+slug` the app's picker offers). Reuse the exact same slug if
   this plan is later regenerated, so Backlog's re-import recognizes it as a new version
   of this plan — clearing the entries nobody has started yet — instead of a second plan.
3. Open the document with one **`plan` entry** — the Roadmap Item the steps fill, shaped
   by the grammar's `## Two levels`: titled with the plan subject; the `+tag`; `repo:` once
   per target repository; the `*priority` the source implies; `due:` only when the source
   states a date; no `effort:`, `!status`, `id:` or body boilerplate.
   Then break the work into ordered step entries, one per unit of work. Every step is
   exactly one of three kinds, decided by who does it — see the grammar's `## Entry kinds`:
   - **`prompt`** — work an AI session runs. Draft every step as one unless it cannot be.
   - **`task`** — work only the user can do even with access they could grant: an action
     in an account or on a machine no AI session can reach, or the sign-off. A decision is
     never a task — the interview asks it now.
   - **`test`** — a check the user runs by hand against work already landed, where the
     source asks for manual acceptance or exploratory testing. Draft it first as a QA
     prompt: an AI session starts the application the way the target repository says,
     drives the scenarios in a browser or harness, and captures evidence of each pass.

   Never combine a prompt with either of the others. A manual step is never a sub-item, checklist line or body
   instruction inside a prompt, and a task never carries instructions for an AI. When one
   unit of work needs both, split it: the manual step becomes its own `task` entry, and
   every prompt that needs it done waits on it with `after:`.

   For each **`prompt`** entry, in this order:
   - **Marker first.** One opening body line in the exact shape of the grammar's
     `## Plan item marker`, restating the entry's `id`, the plan tag, every `repo:` and every
     `after:` — Backlog's copy button drops the metadata line, so this is how an entry pasted
     back out of the app is still recognized and run by `backlog-run-plan-item`. Every prompt
     carries it; write the metadata line first and derive the marker from it, so the two
     never disagree.
   - **Session name second.** One body line telling whoever runs the prompt what to title
     their session, so every session spawned from this plan says which plan and which step
     it is: ``Title this session `<tag>:<n> - <Title>` before you start.`` — the bare tag,
     a colon, then the entry's numbered title exactly as written (grammar's
     `## Step numbers`). Every prompt carries it, worded the same way.
   - **Instructions next.** The rest of the body — concise, no padding — is the entry's
     primary content. Write every interview answer the step depends on into it as a
     settled fact — the chosen option, the exact name, value or wording — never as
     "confirm with the user", "decide whether", "TBD" or a choice left between options.
     A figure stated about the source material — rows, bullets, files, chapters — comes
     from a command run while writing the plan, never from counting by hand, and the entry
     names that command so whoever runs the step can re-derive it. Where no command can
     produce a figure, state none.
   - **Setup sub-items.** A `##` sub-item per repository prerequisite the instructions
     assume (installing a plugin, updating one, wiring a related change), ordered ahead of
     everything else in the entry, titled `Setup: ...`.
   - **Knowledge/devbook reminder.** One more `##` sub-item reminding whoever runs the
     prompt to update the target repository's own knowledge folders or devbook once it is
     done. Every prompt carries this.

   For each **`task`** entry: a title naming what the user does, then a body addressed to
   the user — what to do and what "done" looks like, concise. No marker, no session-name
   line, no `Setup:` or knowledge sub-item: those direct an AI session, and a task has
   none. `- [ ]` checklist lines are fine for the user's own steps. Every task or test but
   the sign-off closes its body with one line, `Kept manual: <reason>`, in the user's
   words from the interview.

   A **`test`** entry is shaped like a task: a title naming what is checked, a body saying
   what to exercise and what a pass looks like, `- [ ]` lines for the individual checks,
   and `after:` on every prompt whose work it checks.

   The **metadata line** of every step, any kind: the type — `prompt`, `task` or `test`,
   never `idea`; always `!ready`, on every entry whatever its place in the chain — order
   is carried by `after:`, never by holding a later entry at `!draft`; always an
   `effort:<points>` estimate off the 1/2/3/5/8/13/21 scale, sized per
   [Sizing the steps](#sizing-the-steps); `repo:<name>` on every step, whatever its kind — a
   prompt once per repository it changes, a task or test once per repository its work is
   done in, on or for, and every repository the plan targets when it concerns none of them
   in particular, so no step is left unassigned in Backlog; `id:<slug>` on every entry — a
   stable slug from its title, reused verbatim when the plan is regenerated, since it is
   how Backlog recognizes an entry already under way or already finished; `after:<id>`
   once per prerequisite, including across repositories and across kinds; the shared
   `+tag`; and only the `*priority`, `@area` or `due:` the source material actually
   implies.

   Once the steps are drafted, and before sizing them, run the interview's second round.
4. Close every step-level plan with two entries, in this order and last in the document.
   Never omit either, however small the plan.
   - The **review prompt**, titled `Review the <plan subject> plan for anything missed`. It
     carries `id:review-plan`, `after:` each step nothing else depends on — the plan's
     leaves, which is every step transitively, tasks and tests included, never the `plan`
     entry — and `repo:` once per repository the plan targeted. Its body asks whoever runs it to read the source material
     against what actually landed: every entry done, and nothing dropped, deferred or left
     half-finished along the way; anything still outstanding is written up as a new entry
     rather than noted and forgotten. It opens with the marker and session-name line like
     every other prompt, but carries no knowledge/devbook reminder — it changes no
     repository of its own.
   - The **sign-off task**, titled `Sign off the <plan subject> plan`. It carries
     `id:sign-off-plan`, `after:review-plan`, `effort:1` and, like the review, `repo:` once
     per repository the plan targeted. Its body asks the
     user to read the review's outcome and confirm the plan is complete, or pick up the
     follow-up entries it wrote.
5. Number the steps: prefix every step title — review and sign-off included, never the
   `plan` entry — with `<n> - `, counting from 1 in document order, and write each prompt's
   session-name line from the numbered title. Numbers are display, not identity: a
   regenerated plan renumbers freely while `id:` stays put. Then assemble the entries into
   one Markdown document per `assets/backlog-import-grammar.md`.
6. Produce the output: write it to the given path (default `<plan-slug>-import-plan.md` in
   the current working directory) when a file was asked for or implied, and show the full
   text inline either way so it is ready to paste directly.
7. Build the review view, always, next to the raw plan: copy `assets/plan-review.html`,
   replace `{{PLAN_TITLE}}` with the plan subject as a short name (e.g. `VS Code desktop
   rollout plan`) and `{{PLAN}}` with the plan text verbatim (it must not contain
   `</script>`), and change nothing else. Publish it as an artifact when the host offers
   one — a private page whose link the user can open beside the raw text; otherwise write
   it beside the plan as `<plan-slug>-import-plan.html` and say to open it in a browser.
   The page parses the embedded plan itself, so the view can never disagree with the raw
   text; it shows the checks of `## Output expectations`, the dependency order as a
   diagram, and every entry with its boilerplate folded away, with the raw plan on a
   second tab. Its **Checks** mirror `## Output expectations`, so the reviewer sees at a
   glance what the plan gets wrong; when the user reports a failed check, fix the plan and
   regenerate the view rather than patching the view.
8. Report the output location (if written), the review view's link or path, the entry
   count, the repositories targeted, the dependency chain, the interview's answers and the
   prompts each went into, which drafted tasks or tests became prompts, every step kept
   manual with its reason, and which sizing answered — the
   `estimate` skill, or this skill's fallback and the step it anchored on. Stop — do
   not open the Backlog app, run a prompt, or create a pull request.

## Interview

Ask with the host's question tool where it has one — several questions per round, each
with the options the source supports and a recommended one first — otherwise as one
numbered list in chat, and wait for the answers. Ask only what the source and the target
repository do not already answer; read the repository before asking about it.

- **Round one, before drafting** — everything a prompt would otherwise stop to ask:
  - *Decisions:* each open question noted while reading, and each choice the work forces
    that the source leaves open — an approach, a name, a scope edge, wording a user sees.
  - *Values:* inputs the work needs that are not in the source or the repository — a
    version, an endpoint, an identifier, a date. Never ask for a secret's value; ask where
    the session will find it (a signed-in CLI, a user-secret, an environment variable).
  - *Access:* for work in an account, a service or on a machine, whether an AI session can
    be given a way in — a signed-in CLI, an MCP server, a test account, the running
    harness. Access the user grants becomes a `Setup:` sub-item of the prompt that uses it.
  - *Acceptance:* for each check the source leaves to a person, what a pass looks like, so
    a QA prompt can run it.
- **Round two, after drafting** — one question per step still drafted as a `task` or
  `test`, the sign-off aside: hand it to an AI session (as a prompt, with the access it
  needs), or keep it manual, and why. A handed-over step becomes a `prompt`; a kept one
  records the reason as its `Kept manual:` line. Skip the round when nothing is left.
- **Further rounds** whenever writing a prompt turns up a question the answers do not
  settle. Never guess an answer and never leave one for the step to ask.

## Sizing the steps

Size every step in one pass once all of them are drafted, never one at a time as each is
written — a point only means something beside the others.

- **An `estimate` skill, when the session has one.** It is the repository's own sizing
  procedure (devbook-procedures seeds it), held to reference work that already landed, so
  a point means the same in every plan. Invoke it with each step's title, kind and
  instructions and write the points it returns unchanged.
- **Otherwise, this fallback**, which is relative within this plan only. Anchor on the most
  typical step and give it `3`; size every other step against it on the 1/2/3/5/8/13/21
  scale — a fraction of its work is `1` or `2`, about twice is `5`, about three times is
  `8`. Size a `task` or `test` by the user's work the same way. Then compare the steps
  pairwise and fix any pair whose points disagree with how their work compares. A step at
  `13` or `21` is usually two steps: split it unless the source names it one unit.

Either way the sign-off task stays `effort:1`.

## Roadmap-level mode

When asked for the roadmap level, the source is a set of agreed feature chapters and the
document is `plan` entries only: one per chapter, shaped as in step 3, its `+tag` from the
chapter's slug and `after:<tag>` once per chapter its `depends-on` list names. No steps, no
review prompt, no sign-off task — each feature's steps come later from a step-level run
under the same tag. Steps 5–8 apply unchanged.

## Output expectations

- One Markdown document; every entry's body precedes its `##`/`- [ ]` sub-items.
- It opens with its one `plan` entry (roadmap level: holds only `plan` entries), carrying
  exactly one `+tag` and no `effort:`.
- Every step is `prompt`, `task` or `test`, is titled `<n> - <Title>` with steps numbered
  1, 2, 3… in document order, and states `!ready`, an `effort:`, an `id:`, at least one
  `repo:`, and the plan's shared `+tag`; every prompt also opens with the marker line, then the
  session-name line naming `<tag>:<its title>`.
- No prompt contains a manual step in any form — no `Manual:` sub-item, no "ask the user
  to…" instruction — or an open decision: no "confirm with", "decide whether", `TBD`, or
  choice left between options. No task or test contains instructions for an AI.
- Every task or test other than the sign-off is one the user was asked about and kept
  manual, and says why on its `Kept manual:` line; the rest became prompts.
- `after:` correctly expresses the plan's dependency order, including cross-repository
  dependencies and prompts that wait on a task, and never names the other level.
- The last two entries are the plan review, waiting on every leaf of that order, and the
  sign-off task waiting on the review.
- A review view built from `assets/plan-review.html` accompanies the plan every time, and
  none of its checks fail.
- No file changes outside the produced plan document and its review view; no call to the
  Backlog app or GitHub.

## Reference

- `assets/backlog-import-grammar.md`
- `assets/plan-review.html` — the review view template; its checks mirror the grammar.