agentleFS
paoloirrerapaoloirrera/ccgraph/.claude/skills/story-refine/SKILL.md

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

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
  1. Distinctive:

    Prefer resolving a question to deferring it, but an honestly-deferred question (with rationale) is better than a guessed answer.

    line 30
  2. Very specific:

    Keep the story's proven section shape (see the story-new skill's references/story-template.md).

    line 31

≈ “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.

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

/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

  1. Read .local/user-stories/<slug>/story.md.
  2. 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.
  3. 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.
  4. Fold the answers back in: move resolved items into Investigation outcomes, tighten Scope, sharpen the Definition 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-doc can record it.
  5. Show a diff/summary of what changed and confirm before writing.
  6. On confirmation, write the updated story.md and 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-new skill's references/story-template.md).

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.