043 — An idea is relabelled as it becomes a roadmap item, a story and a defined story (#243)

Status: in progress Roadmap: #233

Why

At code level 3 an idea, its roadmap item and its story are one issue, relabelled as it goes, and the labels are where the phase is recorded (agent flow): an overview reads them from the forge without visiting a branch. tp can capture an idea (story 042) and then has nothing that moves it: tp roadmap add and tp story issue each file a new issue, so the number changes at every step and the labels have to be set by hand on the forge, where nothing checks them.

What changes

  • tp idea roadmap N [--epic NAME] [TEXT...] (new): the interview's "not now" ending. Issue N goes from idea to roadmap and gets its line in ROADMAP.md.
  • tp idea story N [TITLE...] (new): the interview's "ready" ending, for an idea or for a roadmap item whose turn has come. Scaffolds the story with (#N) on its heading and no **Status:** line, and relabels the issue story. A roadmap item keeps its line.
  • tp story define (new): on a story branch, labels the story's issue defined once its acceptance has no blank cell.
  • tp story new and tp story issue are refused at level 3, naming tp idea add and tp idea story: capture is the only way in.
  • tp roadmap check takes an item whose issue is labelled story as it does one labelled roadmap.
  • Forge: a label can be removed from an issue (Forgejo, GitLab).
  • docs/idea.md, docs/story.md, docs/roadmap.md.

Acceptance

All at maturity.code: 3; below it each new command is refused as tp idea add is.

tp idea roadmap N [--epic NAME] [TEXT...]:

Issue N Epic Outcome
open, labelled idea named and present, or none named idea removed, roadmap added; - [ ] #N TEXT appended to the epic, the last one when none is named; TEXT is the issue's title when not given
open, labelled idea named, not in ROADMAP.md error naming the epic; labels and file unchanged
not labelled idea any error giving its labels; nothing changed
closed, or does not exist any error; nothing changed

tp idea story N [TITLE...]:

Issue N Outcome
open, labelled idea docs/stories/NNN-slug.md written, headed # NNN — TITLE (#N), with no **Status:** line; idea removed, story added; prints the path. TITLE is the issue's title when not given
open, labelled roadmap the same, roadmap removed; its line in ROADMAP.md stays
labelled story error: it is a story already; no file
labelled none of the three error giving its labels; no file
closed, or does not exist error; no file

tp story define, on a branch story/<n>-<slug>:

Story file for #n Acceptance Issue #n Outcome
present every cell of every table filled labelled story defined added; prints #n defined
present a blank cell, or no table any error naming the file; label not added
present filled labelled defined already says so; nothing changed
present filled not labelled story error giving its labels
none with (#n) on its heading — — error naming tp idea story
any other branch — — error: run it on the story's branch

At level 3:

Command Outcome
tp story new TITLE error naming tp idea add and tp idea story N; no file
tp story issue NNN error: the story has its issue from the idea; no issue
tp roadmap check, an item's issue labelled story no finding
tp roadmap check, an item's issue labelled neither #N is not labelled roadmap, as today

Out of scope

  • The release at level 3: it ships a story by its ready status line, which a level 3 story does not have. The next story under #233.
  • called (#234), and taking defined away when a call sends a story back to refinement.
  • The story's worktree (#193): tp idea story writes the file where it is run.
  • Closing an idea that does not stand up: tp issue close N.
  • Stopping a label being changed on the forge by hand. tp is the only writer by convention; nothing can enforce it.

Decisions

None recorded as an ADR. A roadmap item that becomes a story loses the roadmap label, as the manual has it, so that an overview lists it once; the roadmap lint is widened to match, in place of keeping both labels.

Done when

  • tests express the acceptance table and pass
  • spec updated
  • ADR written if a fork was resolved
  • roadmap ticked and stamped; changelog entry
  • issue closed with a link to the release