story-refine
Skill1 starsChanged 4 months agoMIT-0View on GitHub
Clarify and harden an existing draft story.md — resolve open questions and challenge assumptions before design
In this repository8 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ai-dlcSkill
- commitSkill
- design-docSkill
- pr-draftSkill
- spec-designSkill
- story-newSkill
- tasksSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 30
Prefer resolving a question to deferring it, but an honestly-deferred question (with rationale) is better than a guessed answer.
- Very specific: line 31
Keep the story's proven section shape (see the story-new skill's references/story-template.md).
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/story-refine — clarify a story
Step 2 of the AI-DLC pipeline. Takes a draft story.md and makes it design-ready: resolves open questions, verifies external facts, challenges hidden assumptions, and tightens the Definition of Done. Output is the same story.md, improved in place.
Input
The user's argument is the story slug (folder under .local/user-stories/), e.g. /story-refine weather-tool. If omitted and only one in-progress story exists, use it; otherwise list the candidates and ask.
Steps
- Read
.local/user-stories/<slug>/story.md. - Interrogate it. Produce a short list of the things that must be resolved before a design doc can be written. Draw from:
⏳ open:items already flagged in the story.- Unstated assumptions — transport, statefulness, auth boundary, error semantics, number/data types, dependency choices, target platform (recall: AgentCore requires ARM64).
- Unverified external facts — library names/versions, SDK API shapes, AWS contract details. Verify these against real sources (PyPI, npm, official docs) rather than asserting from memory. Use WebFetch / the aws docs tools where available; if you cannot verify, say so and keep it an open question rather than guessing.
- Scope creep / ambiguity — anything in the description that could be read two ways.
- Ask the user the open questions in a batch (use the question prompt UI). Recommend a default for each where you have a defensible one, so the user can accept quickly. Do not proceed on assumptions the user hasn't confirmed.
- Fold the answers back in: move resolved items into
Investigation outcomes, tightenScope, sharpen theDefinition of Done, and delete the open-questions block once empty. Flag any decision that looks ADR-worthy (a cross-cutting, hard-to-reverse choice) so/design-doccan record it. - Show a diff/summary of what changed and confirm before writing.
- On confirmation, write the updated
story.mdand suggest the next step:/design-doc <slug>.
Principles
- Refining means reducing uncertainty, not adding implementation detail — leave the how to the design doc. If you find yourself writing code or file layouts, that belongs in
/design-doc. - Prefer resolving a question to deferring it, but an honestly-deferred question (with rationale) is better than a guessed answer.
- Keep the story's proven section shape (see the
story-newskill'sreferences/story-template.md).
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
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.

