/backlog — Seed a Backlog from docs/ (Product Owner)

An advisory-then-writing ceremony with one gate. The Product Owner proposes an ordered backlog from the project's own documents; the user edits it; only on explicit confirmation are issues created. Nothing is written to .spark/, and no spec is created here: specs belong to /story-time.

Input

Optional: --label <name> (repeatable) or a steer such as "only the MVP". No other input is needed.

Steps

1. Gather the sources yourself. The product-owner agent cannot read the repo's remote or run gh. Read:
   • docs/ (Markdown/text documents only; read each section's heading and lead paragraph, not full bodies, and note file names and headings, as source references need them. Skip binary or non-text files and name what was skipped in the step 9 report),
   • .spark/constitution.md and ROADMAP.md if present.
   • If there is no docs/ (or it holds no readable documents) and no constitution, name /charter as the first step and stop there. Never invoke it yourself, and write nothing. Same rule as /next-steps.
2. Read the tracker (best effort). Resolve the repo from origin (as step 6 does; no unambiguous origin counts as "cannot see") and try gh issue list --repo <owner/repo> --state all --json number,title,state,body,closedAt --limit 200 and gh pr list --repo <owner/repo> --state all --json number,title,state,body,mergedAt --limit 200 (same call shape as /next-steps, aSPARK issue #110). If gh is missing, unauthenticated, the repo is unresolved or a call fails, say once, in one line, "Could not see the tickets, proposed items are not checked for duplicates", and behave as without this step (every item is new).
3. Delegate to the Product Owner. Invoke the product-owner agent in its propose backlog mode (## Proposing a Backlog in its definition) with the document excerpts (file + section headings), the issues and merged PRs from step 2 (or "tickets not visible"), the constitution excerpt or "none", ROADMAP.md if present, and the user's steer.
4. Show the list as a plan. Present it as a numbered, ordered table: title, problem statement, size (S/M/L), dependencies, source reference docs/<file>#<section>. Drop any item that arrives without a source reference, or whose reference names no file and heading you gathered in step 1: nothing is invented. This check is an instruction to you and the agent, not an enforcement; look at every row yourself. Mark each row against the tracker data from step 2 (skip when it could not be read) with a Status column:
   • new: no open or closed issue, and no merged PR, matches the item's title and scope.
   • covered by #N: an open issue matches title and scope. Not filed.
   • done in #N / PR #M: a closed issue or merged PR delivered it. Not filed.
   • partly covered by #N: an open issue covers only part. Say which of the two you propose: a comment on #N (user posts it; this ceremony never edits or closes issues) or a narrower new item for the uncovered part (retitled, state what is left out). Neither is filed unless the user picks it. Match on title and scope, not on title alone; when unsure, mark covered by #N and say why. The Source: line of an issue this ceremony filed earlier also counts as a match, so re-running right after filing yields only covered rows (nothing new). This matching is an instruction to you, not an enforcement: check every row yourself. Only new items (and a chosen narrower item) are offered for filing by default; the user may explicitly override a row.
5. Let the user edit. They may drop, merge, reorder or reword items. Apply the edits (re-invoke the agent for merges/rewording if useful) and re-show the list. Repeat until the user confirms the final list or abandons it. Abandoning writes nothing.
6. Resolve the repo and labels, once, before filing.
   • Repo: from origin (git remote get-url origin / gh repo view), as in /story-time. Echo the resolved owner/repo to the user. No unambiguous origin → STOP and say so; never guess.
   • Labels: default none. Use labels passed as arguments; otherwise the labels: list in the optional .spark/backlog.yml; arguments win. Echo them (or "no labels"). Apply them with --label; do not assume any particular automation behind them.
7. Ask for explicit confirmation to file, naming the count, repo and labels. If the repo is public, say so here, once: the content of docs/ goes into the issue bodies. Only a yes in this conversation permits step 8.

8. File in order. For each item run gh issue create --repo <owner/repo> --title '<title>' --body-file - (plus --label per label), feeding the body on stdin from a single-quoted heredoc (<<'ASPARK_BACKLOG_BODY'). Never put text from docs/ inside double quotes: the shell would run any backtick or $(...) in it. If any body line equals the delimiter, pick another one: that line would end the heredoc and the shell would run the rest. In the single-quoted title, write each ' as '\''. Record each returned issue number; in later bodies, refer to dependencies already filed as #<n>, otherwise by title. The body is exactly:

   ## Problem
   <short problem statement>
   
   **Size:** <S|M|L>
   **Depends on:** <#n, titles, or none>
   **Source:** <docs/<file>#<section>, or the constitution / ROADMAP.md section>
   
   generation: 0

   This is the shape /story-time <n> imports as the idea. If gh is missing, unauthenticated or a call fails, stop, report the real error and list the issues created so far. Never retry silently or claim success. If the user fixes the cause in this conversation, offer to file only the items not yet created, re-confirming per step 7, so nothing is duplicated.

9. Close with a report stating: repo, issues created (number + title), items skipped as covered/done (with #N), the "Could not see the tickets" line if it applied, labels applied, items dropped for lack of a source, files in docs/ skipped as non-text in step 1 (or "none"), and that /story-time <n> or /spark starts any of them.

Rules

• Never create an issue before the explicit confirmation in step 7.
• Never file an item marked covered, done or partly covered unless the user explicitly overrides that row. Never edit or close existing issues.
• Never write or modify files under .spark/.
• Every item has a docs/<file>#<section> source (or the constitution's section or ROADMAP entry named as such); otherwise it is not proposed.
• Labels are optional and tracker-agnostic; default is none.
• Every issue carries the generation: 0 line.

Handoff

• Issues filed → /story-time <n> or /spark per issue, on the user's go.
• User abandons → stop; nothing persists.