agentleFS
Sign inStart free
ShiningPlagueShiningPlague/shiningplague-studio/skills/story-readiness/SKILL.md

story-readiness

Skill0 starsChanged 4 months agoMITView on GitHub

Validate that a story file is implementation-ready before a developer picks it up. Checks the story's required sections, that its governing ADR is Accepted, that its embedded control-manifest version is current, and that every acceptance criterion is testable. Runs between /create-stories and /dev-story, and during /sprint-plan story selection. Returns READY / READY WITH GAPS / NOT READY.

9 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use vertical-slice.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • hongyuancSkill

    vertical-slice

    Build and evaluate a production-quality vertical slice before advancing from Pre-Production to Production.

    Also in 4 projects that use this

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 9 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read the ADR the story names and find its ## Status heading.

    line 58
  2. Distinctive:

    Every criterion must be specific enough that a developer knows unambiguously when it is done.

    line 85
  3. Very specific:

    NOT READY on an ADR → /architecture-decision

    line 140
  4. Very specific:

    NOT READY on criteria → /create-stories [epic-slug] to rewrite, or edit the story in place with the user

    line 141

“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Story Readiness

The gate between a story exists and a developer starts work. It is cheap to run and it is the only thing standing between a vague acceptance criterion and a week of rework.

🌱 ShiningPlague Studio skill. The pipeline step /create-stories → /story-readiness → /dev-story → /code-review → /story-done.

If an artifact named here is absent: say so plainly in one line, skip that step, and continue. Never invent the file to satisfy a checklist, and never fail a close because an optional artifact was never created.

Usage

/story-readiness [story-path]     validate one story
/story-readiness                  validate every story in the current sprint

With no argument, read the newest production/sprints/sprint-*.md, take its story list, and validate each one.

Inputs

InputPath
Story fileproduction/epics/<epic-slug>/<story>.md
Governing ADRdocs/adr/NNN-<slug>.md (named in the story)
Control manifestdocs/architecture/control-manifest.md
System GDDdocs/gdd/[system].md or the master docs/GDD.md
Sprint plannewest production/sprints/sprint-*.md (no-argument mode only)

Procedure

1. Read the story

Confirm the story carries every section /create-stories writes: Story Type, GDD Reference (TR-ID), Governing ADR, Acceptance Criteria, Test Evidence, Out of Scope, Manifest Version.

A missing section is a finding, not a crash — record it and keep going.

2. Check the governing ADR

Read the ADR the story names and find its ## Status heading.

ADR stateVerdict
Acceptedpass
Proposed / DraftNOT READY — run /architecture-decision to land it first
Superseded / DeprecatedNOT READY — the story is written against retired rules
No ## Status section at allNOT READY — say so explicitly; this check cannot pass silently
Story names no ADRfinding only — fine for Config/Data and Visual/Feel stories, a gap for Logic and Integration

The "no ## Status section" row exists because a status check that silently passes everything is worse than no check. /adopt classifies that same gap as BLOCKING for exactly this reason.

3. Check control-manifest drift

Compare the story's embedded Manifest Version with the Manifest Version field in docs/architecture/control-manifest.md.

  • Same date → pass.
  • Story older → READY WITH GAPS: "This story was written against the [date] manifest; the current manifest is [date]. Re-read the layer rules before implementing, or regenerate the story."
  • Manifest absent → one line saying so, skip this check.

4. Testability pass over the acceptance criteria

Every criterion must be specific enough that a developer knows unambiguously when it is done. Judge by story type:

Story TypeA criterion is ready when…
Logicit can be verified by an automated test — named inputs, named expected output
Integrationit is observable in a running build, with the observation stated
Visual/Feelit names what evidence proves it (screenshot, capture) and who signs off
UIit names the screen, the interaction, and the expected end state
Config/Datait names the data file and the value range, not just "tune it"

Flag any criterion containing an unmeasurable word — feels good, fast, polished, intuitive — unless the story also states how it will be judged.

5. Dispatch the QA lead

Spawn qa-lead with gate QL-STORY-READY from .claude/docs/director-gates.md. Pass: story path, story type, acceptance criteria verbatim, the GDD requirement. Await the verdict and fold it into the report.

Skip this step in lean or solo review mode (production/review-mode.txt) — say one line that you skipped it and why.

6. Report

## Story Readiness: [story title]

**Verdict:** READY | READY WITH GAPS | NOT READY

| Check | Result |
|---|---|
| Required sections | [pass / missing: ...] |
| Governing ADR status | [Accepted / ...] |
| Manifest version | [current / stale ([story date] vs [manifest date]) / manifest absent] |
| Acceptance criteria testable | [N/N / N of M — see below] |
| QL-STORY-READY | [verdict / skipped — lean mode] |

**Blockers** (NOT READY only)
- [what must change before implementation starts]

**Gaps** (proceed, but knowingly)
- [what is imperfect and what it will cost]

Verdict meanings

  • READY — hand it to /dev-story.
  • READY WITH GAPS — implementable, but state the gaps out loud first and let the user decide whether to fix the story or accept the risk.
  • NOT READY — name the one thing that must change. Do not start implementing.

Recommended next steps

  • READY → /dev-story [story-path]
  • NOT READY on an ADR → /architecture-decision
  • NOT READY on criteria → /create-stories [epic-slug] to rewrite, or edit the story in place with the user

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free