Product issues
Turns the items in docs/product/<slug>/roadmap.md into implementable slices at docs/product/<slug>/issues/, one markdown file each, then files them as GitHub issues if you ask. Refuses when no roadmap has been written.From its SKILL.md
npx -y skills add Tsadoq/claude-better-plan --skill product-issuesAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
15.1 KB, as published. Nobody here has run it
/product-issues
You read a finished docs/product/<slug>/roadmap.md and write
docs/product/<slug>/issues/, a folder holding one markdown file per slice of
work. product-roadmap is your input and the only member you derive from. The
roadmap says what gets built and in what order; an item there is a group of
requirements that made sense to score together, which is a different thing from
a piece of work one person can pick up and finish, and supplying those pieces is
the whole of what this beat adds.
issues/ is not a sixth chain member. The family is closed at five, brief.md
through roadmap.md, and this folder sits beside them rather than after them.
Two facts follow from that and shape every step below.
This is the only beat whose output can leave the repository. Every other one
writes a markdown file that a reviewer reads as a diff and undoes with
git checkout. A create call against somebody's tracker cannot be undone, and a
batch that dies halfway leaves an unknown subset filed against a team that did
not ask for it. That is why step 4 shows a dry run first and files nothing
without being told to, and why the destination is asked rather than assumed.
No freshness check in this suite reads a slice. Nothing downstream of
roadmap.md is a chain member, so nothing will ever tell you that the roadmap
moved after a slice was cut from it, or that a slice id changed under something
citing it. ## Re-run behaviour at the bottom of this file is therefore read
before a second run touches an existing folder, not after.
Three reference files govern this, and none of them is restated below. Read them now; do not work from memory on anything they own.
${CLAUDE_PLUGIN_ROOT}/skills/product-issues/references/story-map-template.mdis the shape and the rules: the backbone and what may never be on it, what row one is and the one question it has to pass, the five SPIDR patterns, where the INVEST gate is published, the frontmatter schema every slice carries, and the six body sections with the roadmap sha among them.${CLAUDE_PLUGIN_ROOT}/skills/product-issues/references/product-issues-principles.mdis the judgement. Its plan-time principles act while you cut; its red-flag clusters are how a later review will read the set you wrote.${CLAUDE_PLUGIN_ROOT}/skills/product-artifacts/references/artifact-family.mdis the contract: the chain's members, the provenance rules, and the unknown marker's exact literal.
What this beat adds to those three is two decisions and one discipline. The decisions are where the cuts fall — which slices an item becomes, which nothing upstream settles — and where the slices go, which is the user's to make and not yours. The discipline is that nothing is filed that the user has not seen first. All three are worth stating because none is checkable afterwards: a set cut down architectural layers looks exactly as finished as one cut across a backbone, and a filed issue nobody reviewed looks exactly like a filed issue somebody did.
Step 1: Refuse unless the roadmap conforms
$ARGUMENTS is the slug. If it is empty, ask for it with AskUserQuestion
before anything else — a slug names someone else's folder and cannot be guessed.
Ask the substrate whether the upstream is there:
python3 ${CLAUDE_PLUGIN_ROOT}/skills/product-artifacts/scripts/product_artifact.py \
--check-freshness --slug <slug> --product-dir docs/product
One call answers presence and provenance for the whole chain: read roadmap.md's
state out of the entry's members map. Derive no state of your own from the
files. Do not stat the folder, do not read a provenance line yourself, and do not
compute a sha — a second reader of those bytes is a second answer that can
disagree with the one every other beat gets.
Read that entry for roadmap.md and stop there. This beat gates on its
immediate upstream alone: whether spec.md has moved under roadmap.md is a
state product-roadmap already decided to live with, and a run that refuses over
it re-opens a question two beats away from anything it writes.
Never create the folder either. --ensure-folder is the only entry point in this
suite that writes anything outside a member, and this beat never reaches for it:
it refuses unless roadmap.md is already there, and a roadmap.md that exists
sits in a folder somebody else already made. The one directory this beat creates
is issues/ itself, inside a folder that already exists.
Then three refusals, in this order. Stop at the first one that fires, say which
of the three it was, and name product-roadmap as the beat to run:
roadmap.mdis absent. Its state isabsent, so there is nothing to cut: a slice is cut from an item, and there are no items.- Its provenance is
unresolvable. What puts a member in that state is written in the artifact-family contract and nowhere else; read it there. What it means here is that nobody can say whichspec.mdthis roadmap was derived from. Slicing it anyway would put work in front of a team on the authority of bytes of unknown ancestry, and every slice would record a sha of them. - No item carries an
ITEMid. Readroadmap.mdfor ids of that form. With none there is nothing for a slice'sroadmap_itemkey to name, so every slice would be unmoored by construction — and pre-flight refuses a set whoseroadmap_itemvalues are not ids present in that member, so a run that carried on would refuse at the far end having done all the work first.
stale is not one of the three. A roadmap.md whose own upstream has moved on
is still a roadmap, and refusing over it would have this beat re-decide something
product-roadmap owns. Report the state to the user, say a re-run of that beat
would settle it, and carry on.
The third refusal is the one no script can make for you. Never invent an ITEM
id, and do not offer to slice from spec.md or requirements.md instead. Five
beats stand between a brief and this folder precisely so that everything filed
here is work somebody already committed to building, in an order somebody already
argued for.
Step 2: Ask where the slices go
Ask with AskUserQuestion, and ask before cutting rather than after, because the
answer decides what step 4 does and what the user has to have ready. Two options:
- markdown — stop when the folder is written. The slices are on disk,
reviewable as a diff and revertible with
git checkout, and nothing leaves the repository. - GitHub — write the folder, then file the slices as issues into a repository
the user names. This needs
owner/name, and optionally the number of a parent issue to file the batch under; ask for both in the same call.
GitLab and Jira are not implemented. Say so plainly if either is asked for, and do not offer to improvise one. This suite captures its fixtures from real invocations rather than writing them from memory, and neither tracker could be reached from where this was built: shipping a wire format nobody has exercised, behind a menu entry that looks like the two that work, is worse than the absence. What is available instead is the markdown destination, whose files somebody can paste, import, or file by hand.
The answer changes nothing about step 3. The slices are the same bytes either way, which is deliberate: a set cut with one tracker in mind is a set carrying that tracker's assumptions, and this folder outlives any of them.
Step 3: Cut the slices and write the folder
Work from roadmap.md and the story map template. Read that template before
cutting rather than after — the backbone, row one and its test, and the SPIDR
patterns are all its to state, and the split it warns against is exactly the one
a run produces when it has read only the instruction here.
Four things are this step's to settle, and the template says what each one has to satisfy:
- The backbone. The template defines it and gives the one test it has to pass; what this step decides is which activities this product's items sit under.
- Row one, and whether it passes the template's one question. Everything else is a later row.
- Each cut, made with a named SPIDR pattern rather than by making things smaller until they look small.
- The id width, settled before the first id is written. The template says why it cannot be revised afterwards.
Every slice passes the INVEST gate before its file is written. The gate lives at
${CLAUDE_PLUGIN_ROOT}/skills/product-requirements/references/requirements-template.md
under ## The INVEST gate, is cited by the template, and is restated in neither
place — go and read it.
Then write one markdown file per slice into docs/product/<slug>/issues/, and
put nothing else in that folder. Frontmatter keys and body sections are the
template's; two of them are worth naming here because they are the ones a run
gets wrong quietly:
roadmap_itemnames theITEMid the slice was cut from, and every slice carries one. A slice with no upstream basis is work somebody added on the way past.## Referencescarries a sha ofroadmap.md. Which value it is, where to take it from, and what its format must not borrow are all the template's to say, and all three are things a run will supply from memory if it does not go and look.
A slice with an open question in it is not filable. Where a value nobody has
established would go, the unknown marker goes instead — its literal and payload
rules live under the ## Unknown marker heading of the artifact-family contract,
so copy them from there rather than reconstructing either. Pre-flight refuses the
whole batch over one such slice rather than filing the rest, because a partial
batch missing exactly the undecided slice looks complete. Decide it, or leave
that slice out of this run.
Step 4: Show the dry run, then file only on explicit confirmation
If the destination is markdown, report what step 3 wrote and stop:
python3 ${CLAUDE_PLUGIN_ROOT}/skills/product-issues/scripts/file_issues.py \
--slug <slug> --product-dir docs/product --destination markdown
If it is GitHub, run the same command without --file first. That is not a flag
you may skip: without it the run builds a transport that describes every call and
makes none.
python3 ${CLAUDE_PLUGIN_ROOT}/skills/product-issues/scripts/file_issues.py \
--slug <slug> --product-dir docs/product --destination github \
--repo <owner/name> [--parent <n>]
One thing the preview cannot cover, and the user hears it before they confirm
rather than after. Reading the parent issue's current children and its depth is
itself a call, so a dry run does not make it: the run reports ceilings as
unread, and the two refusals that rest on those numbers — too many sub-issues
under one parent, too deep a nest — cannot fire until the real run. A batch that
was confirmed on a clean preview can still be refused with nothing filed.
Show the user what came back, in these terms: how many slices are planned, how
many were skipped as already filed, what ceilings says, and the calls the
run would have made, each one a summary and the call itself. Then ask for
confirmation in that turn, for that sequence. The destination answer in step
2 is not it: that was a choice of where, made before anybody could see what would
be sent.
Only then re-run the same command with --file appended. Never put --file on
the first run, never file a sequence the user has not been shown, and never file
a shorter or longer set than the one they confirmed.
The script refuses on its own account before any call goes out, and its refusals
are yours to report rather than to work around: a slice carrying the unknown
marker, a batch that would push the parent past a hundred sub-issues or past the
nesting ceiling, and a slice whose roadmap_item names no ITEM in
roadmap.md. Each refuses the whole batch with nothing filed. Fix the slices and
run the dry run again; do not file the remainder by hand.
If a run fails part-way, it prints its report alongside the error. Read issues
there before doing anything else: those slices are filed and their ledger entries
are already written, so the fix is a second run, which skips them.
Step 5: Report
Report the folder written and how many slices it holds, how many activities the backbone came out as, and — where a tracker was the destination — how many were filed, how many were skipped as already filed, and into which repository.
Then say plainly what this folder is not. It is not a chain member and nothing
checks it: no freshness check reads a slice, so nothing will report that the
roadmap moved under one, and the sha in ## References is there for a person to
check by hand. It is also not a plan. How any one slice gets built is
/deep-plan's question, asked with research this beat did not do.
Re-run behaviour
A second run adds to issues/. It does not rewrite the folder, and the
reason is the ids.
- A slice id is never renumbered and never reused. A re-run gives new slices the next numbers after the highest ever used in this folder, retired ones included, and leaves every existing id exactly as it is.
- A slice already carrying a
filed_<destination>entry is skipped and counted as skipped, which is what makes a second run file the remainder rather than a duplicate set. Two layers enforce it: the run skips such a slice, and the adapter refuses a batch that still contains one. Never delete or edit a ledger entry by hand — that is precisely how a duplicate gets filed, and the tracker will not tell you. - A slice that has been filed is not rewritten in place. The tracker holds a copy of its body and nothing in this beat updates one, so an edit here would leave two versions with no way to tell which the implementer read. Cut a new slice, and say in it what changed.
- A slice the re-run decides against is retired by leaving it alone, not by
deletion. Its id stays where it is; other slices'
## Blocked bysections name ids, and a deleted file makes a reference nobody can resolve.
Why the rule exists, and not only what it says. A slice id is cited from outside
this folder — by other slices, and by whatever was filed to a tracker where no
check in this suite reaches. The chain's mechanism compares an upstream's content
hash and never inspects a downstream identifier, so a renumbering that tidies the
folder leaves every member reporting fresh while every citation into it now
points at different work. A review is the whole of this rule's enforcement.
This beat never writes to roadmap.md. Not to add an ITEM a slice wanted,
not to reword one so a slice traces to it more neatly, not to record that
something was filed. Every slice carries a sha over that file's bytes, so editing
it would date the whole folder the moment the folder was finished, over an edit
nobody asked for. The same holds for every other chain member. Anything the
roadmap gets wrong is reported to the user as a product-roadmap re-run.