agentsclimarketplace

Product requirements

Skill Tsadoq/claude-better-plan/skills/product-requirements

Turns a written discovery into testable requirements at docs/product/<slug>/requirements.md: one EARS sentence per thing that must be true, functional and non-functional, each traced to the opportunity it answers. Refuses when no discovery has been written.From its SKILL.md

Install
npx -y skills add Tsadoq/claude-better-plan --skill product-requirements

Assembled 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

11.6 KB, as published. Nobody here has run it

/product-requirements

You read a finished docs/product/<slug>/discovery.md and write docs/product/<slug>/requirements.md. Discovery argues which customer opportunities are worth answering; your job is to restate those answers as sentences somebody could write a test against. This is the beat where the chain's ambiguity gets spent. Everything upstream of you is deliberately prose, and neither a narrative brief nor a ranked bet is falsifiable one sentence at a time. What the resulting document holds, section by section and field by field, is the template's to state rather than this file's.

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-requirements/references/requirements-template.md is the shape and the grammar: which sections requirements.md carries and what belongs in every field, the EARS notation every requirement is written in, the casing it mandates, the quality characteristic checklist, the INVEST gate, and how a REQ id is formed.
  • ${CLAUDE_PLUGIN_ROOT}/skills/product-requirements/references/product-requirements-principles.md is the judgement. Its plan-time principles act while you write; its red-flag clusters are how a later review will read what you wrote.
  • ${CLAUDE_PLUGIN_ROOT}/skills/product-artifacts/references/artifact-family.md is the contract: the section names and their order, the provenance rules, and the unknown marker's exact literal.

Two failures this beat exists to prevent, and they are not the same failure. The first is a requirement that answers no opportunity. Every row here is downstream of something a customer was observed struggling with, so a requirement traceable to no OPP id is scope somebody added without deciding to — and it will be built, because by the next beat it is indistinguishable from the ones discovery earned. The second is a requirement nobody could fail. A sentence that reads like a constraint and admits no test is worse than a missing requirement: the missing one is visible in the coverage table, and the untestable one occupies the row that would have shown it missing.

Step 1: Refuse unless discovery 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 discovery.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.

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 discovery.md is already there, and a discovery.md that exists sits in a folder with an index row somebody else already made.

Then three refusals, in this order. Stop at the first one that fires, say which of the three it was, and name product-discovery as the beat to run:

  1. discovery.md is absent. Its state is absent, so there is no upstream to derive from at all. Run product-discovery for this slug first.
  2. Its provenance is unresolvable. The line is missing, malformed, or names an upstream that does not exist, so nobody can say which brief.md this discovery was derived from. Deriving from it anyway would put a sha over bytes of unknown ancestry into requirements.md and make this member's provenance look sound while the chain behind it is broken.
  3. No opportunity node carries an OPP id. Read the tree in discovery.md for ids of that form. With none, there is nothing for a requirement's Traces to cell to name and nothing for the coverage table to have a row per, so every requirement you wrote would be untraceable by construction.

stale is not one of the three. A discovery.md whose own brief has moved on is still a discovery, and refusing over it would have this beat re-decide something product-discovery 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, and the one worth refusing over. Never invent an opportunity id, do not renumber the tree to produce one, and do not write the member with the coverage table left out. Do not offer to proceed from the brief instead: two beats stand between a brief and a requirement precisely so that the sentences here answer something observed rather than something argued.

Step 2: Take the opportunity set and name the system

Work from discovery.md and nothing else. Read out, before writing any requirement:

  • Every OPP id in the tree, including the ones no solution was proposed for. The coverage table has a row per id, so the set is fixed here rather than accumulated as you write. Collecting it afterwards from the requirements you happened to produce yields a table that indexes your own output instead of checking it.
  • The one name for the thing being constrained. Every requirement sentence has a slot for the system it constrains, and the template states what that name is and where it may come from.

Ask the user with AskUserQuestion only where discovery.md genuinely does not answer one of these. It settles what the opportunities are; it does not always settle what the system is called.

Step 3: Write the requirements, then work the checklist and the gate over them

The order matters and is not the order the template's sections appear in.

  1. One requirement per thing that has to be true, each written in an EARS pattern, each naming the OPP id it answers. The template owns the grammar, the casing and the id notation; follow it rather than this file on any of them.
  2. Then the quality characteristic checklist, over the set you have. It is what makes the non-functional surface enumerable rather than whatever came to mind, so it is worked through after the functional rows exist and not instead of them.
  3. Then the INVEST gate, over the requirements it applies to. It judges a requirement already written, so running it first would be judging a sentence nobody had committed to.

Two rules while writing, both of which the rubric will be read against later:

  • Never leave a slot to a plausible value. A threshold nobody established takes the unknown marker, whose literal and payload rules live under the ## Unknown marker heading of the artifact-family contract cited above. Copy them from there rather than reconstructing either from memory. A number you produced is cited by the next beat and never questioned again.
  • Never name a mechanism. A requirement that names a button, a screen, a library or an endpoint has smuggled a solution into the document that exists to constrain one, and the rubric has a cluster whose whole job is finding it.

Step 4: Get the provenance line, then write

Read the finished provenance line off the substrate; do not assemble it, and do not compute a sha yourself:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/product-artifacts/scripts/product_artifact.py \
  --provenance-line --slug <slug> --member requirements.md --product-dir docs/product

Write its line field into requirements.md verbatim. The --member argument is what makes the line this member's own: it names the member being written, and the sha comes back over that member's upstream. If the field is null, the upstream you refused over in step 1 is still missing — go back rather than inventing a line.

Say in one line what ## Re-run behaviour below states, then write the file: the sections in the order the artifact-family contract publishes them, filled per the template.

Never write to discovery.md. Not to fix a tree, not to add an id you needed, not to reword an opportunity so a requirement traces to it more neatly. Editing the upstream changes its bytes, and the sha you have just written into requirements.md is over those bytes: the edit would mark the file you are writing stale the moment you finish it. Anything discovery gets wrong is reported to the user as a product-discovery re-run.

Step 5: Report

Report the path written, how many requirements it carries, how many OPP ids came back not addressed, and how many unknown markers are in it.

Then state plainly what this document is not. It is not a design and not a plan: it says what has to be true of the product, and every question of how is the next beat's. A reader who takes a requirement for a work item will estimate it, and a non-functional row carrying a latency threshold is not a work item.

An uncovered opportunity is not a failure and never a reason to refuse to write. A requirements.md recording three opportunities as not addressed has done its job; one covering all of them, written from a discovery nobody interrogated, is the one that should worry a reader. Do not close a gap by writing a requirement nobody asked for — the row saying nothing answers it is the finding.

Re-run behaviour

A second run revises requirements.md in place. This is the one beat in the suite that does not overwrite its member, and the reason is the ids.

  • A requirement that survives the re-run keeps the number it already has, however much its wording, its pattern or its Traces to cell changed.
  • A new requirement takes the next number after the highest ever used in this file, retired numbers included. Never the count of live requirements: a deletion would then free a number for something else.
  • A requirement the re-run drops moves to ## Out of scope with the reason it went there, rather than disappearing.
  • A retired number is never reused. REQ7 names one requirement for the life of the folder, whether or not REQ7 is still live.

Why the rule exists, and not only what it says. REQ ids are cited by the beats downstream of this one: a spec references a requirement by number, and so does whatever plan is written from that spec. Nothing in the chain will ever tell you a number has moved — the freshness mechanism compares the upstream's content hash and never inspects a downstream identifier, so a wholesale renumber leaves every member reporting fresh while every citation in the folder now points at a different sentence. A review is the whole of this rule's enforcement. Read it as bookkeeping you are free to tidy and the breakage is silent, surfaces beats later, and looks like somebody else's mistake.

Announce the revision in step 4 as a statement, not a confirmation prompt: do not ask permission and do not offer to overwrite instead. The previous version is not recoverable, docs/product/ being gitignored, so the ids in the file you are reading are the only record of what they were.

Nothing else on disk changes. This beat creates no folder and refreshes no index: it refuses unless discovery.md exists, and a discovery.md that exists is one whose folder someone else already made.

Keep looking

Skills are one crate of 610,045. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.