Skip to content
Skills Library
Management & product · Planning

specification

/specification

Turn fuzzy intent into shared understanding and acceptance criteria — specification as a conversation, run one question at a time, before any story is split or planned. Use when an idea, feature request, or problem statement has no agreed rules or examples yet ("let's spec this out", "what should this actually do?", "we need acceptance criteria"). Produces an example map and acceptance criteria written back into the team's own story artifact, plus candidate glossary terms and parked questions. The agent-facilitated round is a draft for review by the accountable owner and, when risk or shared o

Repository
.dotfiles ↗
Licence
MIT
Last repository change
02.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 02.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Turn fuzzy intent into shared understanding and acceptance criteria — specification as a conversation, run one question at a time, before any story is split or planned. Use when an idea, feature request, or problem statement has no agreed rules or examples yet ("let's spec this out", "what should this actually do?", "we need acceptance criteria"). Produces an example map and acceptance criteria written back into the team's own story artifact, plus candidate glossary terms and parked questions. The agent-facilitated round is a draft for review by the accountable owner and, when risk or shared o

Triggers from the description

letwhat should this actually do?we need acceptance criteria
Original author description

Turn fuzzy intent into shared understanding and acceptance criteria — specification as a conversation, run one question at a time, before any story is split or planned. Use when an idea, feature request, or problem statement has no agreed rules or examples yet ("let's spec this out", "what should this actually do?", "we need acceptance criteria"). Produces an example map and acceptance criteria written back into the team's own story artifact, plus candidate glossary terms and parked questions. The agent-facilitated round is a draft for review by the accountable owner and, when risk or shared o

How it works

  1. The Contract
  2. The Recommended Path: Draft, Then Accountable Review
  3. The Review Page
  4. Vocabulary Capture
  5. Boundaries
  6. Verification Checklist
Original SKILL.md headings · 87 lines, 1,220 words
SKILL.md preview
---
name: specification
description: Turn fuzzy intent into shared understanding and acceptance criteria — specification as a conversation, run one question at a time, before any story is split or planned. Use when an idea, feature request, or problem statement has no agreed rules or examples yet ("let's spec this out", "what should this actually do?", "we need acceptance criteria"). Produces an example map and acceptance criteria written back into the team's own story artifact, plus candidate glossary terms and parked questions. The agent-facilitated round is a draft for review by the accountable owner and, when risk or shared ownership warrants it, the relevant human perspectives. For decision trees with no artifact, use grill-me where installed or this skill's one-question protocol; for tightening an existing artifact, see find-gaps; for slicing agreed work, see story-splitting.
---

# Specification: the Conversation Is the Product

A specification is not a document. It is a conversation between stakeholders in which shared understanding gets built — and the written result is, at best, an educated guess about what is really required, refined until reality gets the deciding vote (Gorman). The value is in the *planning*, not the plan: asking an agent to "write the spec" while skipping the conversation misses the entire point. This skill exists to *force* the conversation — with you first, then between the humans who own the answers.

**Where this sits**: before `story-splitting`, before `planning`, before any acceptance test exists. Its output feeds all three.

| Resource | Load when... |
|----------|-------------|
| `spec-review-template.html` | Presenting a finished map for accountable human review |
| `references.md` | Checking sources for the practices taught here |

---

## The Contract

1. **Find the story's home first.** Ask where this story lives — an issue, a file under `docs/stories/`, a ticket, anywhere the team already keeps it. Everything this skill produces is written back into THAT artifact. If it has no home yet, ask where it should live; never invent a parallel convention silently.
2. **One question at a time.** Never a questionnaire. Name the stakes and
   accept "park it" — parked questions get an owner and a date, never silence.
   Recommend an answer only when repository evidence or known trade-offs
   justify it; otherwise ask neutrally and label any tentative hypothesis as
   such rather than anchoring the decision owner.
3. **Every material assumption becomes a question.** The moment you notice
   yourself deciding an outcome the human never supplied, stop and ask it. An
   answer that cannot change the map was not a real decision question.
4. **The map is data, not prose.** Build it as you go and keep it visible:

```
story:     <one line, in the words the human used>
rules:     # business policies / acceptance criteria
  - rule: <policy in domain language>
    examples:
      - <concrete: real values, real outcome — never a restatement of the rule>
    questions: # open assumptions attached to THIS rule (optional); parked items include owner and decision/review date
questions: # cross-cutting open assumptions; parked items include owner and decision/review date
acceptance criteria: # distilled from rules once examples stabilise
candidate terms:     # vocabulary the conversation coined or contested
```

5. **Challenge the map before trusting it.** For each rule: the counter-example question ("what would have to be true for this example to come out differently?"), zero–one–many, boundaries, and what-happens-when-it-fails. A rule with one example is a guess; a rule whose examples all agree is a hypothesis.
6. **Read the map's shape as a diagnostic.** Question-dominated → not ready to build; keep talking, or park with owners and stop. Rule-dominated (more than ~6 rules) → too big; hand the map to `story-splitting`. Balanced, with concrete examples per rule → ready.

## The Recommended Path: Draft, Then Accountable Review

The agent-facilitated conversation above produces a **first draft** of shared understanding. It becomes usable only after the people accountable for the outcome review it. Match the review group to the work: a sole owner may be enough for a low-risk local change; shared, regulated, irreversible, or cross-discipline behavior needs the affected business, development, testing, security, operations, or design perspectives. Record any material perspective intentionally absent and why.

**Recommended flow, multi-round:**

1. **Round 1 (agent-facilitated)**: run the contract above with whoever brought the idea. Write the map back to the story artifact. Generate the review page (below) from it.
2. **Round 2 (accountable humans)**: the review page goes to the owner and the risk-relevant perspectives. A three-amigos conversation (business, development, testing) is a strong default for shared product behavior, not a ceremony to manufacture for every small task. Reviewers annotate the page; disagreements become new questions, not silent edits.
3. **Round 3+ (reconcile)**: their feedback returns to the agent round as answers and new red cards. Update the map and the artifact; regenerate the page. Repeat until a round produces no new rules, no changed examples, and no new questions.
4. **Then split**: the stabilised map goes to `story-splitting`; each child story carries its rules and examples onward — per-rule questions flatten into the single questions list that downstream mapping expects — and where an acceptance-test outer loop is installed, those examples become the seed of its per-slice mapping.

Reality still gets the final vote: acceptance criteria written here are hypotheses until the shipped slice confirms them. When reality disagrees, the conversation reopens — that is a feature of the method, not a failure of the spec.

## The Review Page

For round 2, generate a single self-contained page from `resources/spec-review-template.html`: fill its JSON data slot (replace ALL occurrences of the double-underscore REVIEW_DATA token, escaping every `<` in string values as backslash-u003c), write to a temp directory, open locally, never commit the generated page. Structure the data as sections sharing one card engine: a **Rules** section (one card per rule — the rule as the card name, its concrete examples as the plain text, its attached questions in the highlight line, the verbatim map entry collapsible beneath), a **Parked questions** section (question as name, owner + decision/review date + context as plain text), and a **Candidate vocabulary** section (term as name, one-line gloss as plain text). Every card takes comments; the copy-feedback control assembles all annotations into one markdown block that returns to the next round. This page is a conversation artifact, not an approval record — regenerate it freely every round.

## Vocabulary Capture

Specification conversations coin vocabulary constantly — that is half their value. Every term the conversation invents, contests, or uses in two different senses goes into `candidate terms` with a one-line gloss. Where the `ubiquitous-language` skill is installed, candidates enter its five-step language protocol individually (extraction gathers candidates; only the protocol admits them); where it is not, the candidate list still travels with the story so the naming conversation happens somewhere.

## Boundaries

| Situation | Skill |
|-----------|-------|
| A fuzzy decision tree, no artifact yet, resolving choices | `grill-me` where installed; otherwise this skill's one-question protocol |
| An existing story/plan/spec that needs holes poked | `find-gaps` |
| The agreed map is too big; slicing into child stories | `story-splitting` |
| Turning a child story into PR-sized plans | `planning` |
| Comparing libraries, tools, applications, services, platform primitives, or bespoke implementation after behavior and constraints stabilize | `evaluate-existing-solutions` |
| Per-slice executable specification (where installed) | `acceptance-testing` |
| Naming the vocabulary the conversation surfaced (where installed) | `ubiquitous-language` |

## Verification Checklist

- [ ] The story artifact's home was asked, not assumed; all output written back into it
- [ ] Questions went one at a time; recommendations appeared only when evidence or known trade-offs justified them
- [ ] Every rule has at least one concrete example (real values, real outcome)
- [ ] Each rule survived the counter-example challenge
- [ ] Parked questions have owners and decision/review dates
- [ ] Candidate terms captured (and routed to the language protocol where installed)
- [ ] The accountable owner reviewed the page; risk-relevant perspectives joined or their absence was recorded
- [ ] Feedback returned as answers/questions, never as silent edits
- [ ] Map shape checked: not question-dominated, not rule-dominated, examples concrete
Files in this package (3)
  • SKILL.md 9 KB
  • resources/references.md 2 KB
  • resources/spec-review-template.html 10 KB

Versions

RepositoryScoreLicence
This page · citypaul/.dotfiles100MIT
forgivesam168/ai-dev-workflow100Apache-2.0
bis-med-it/marco-BIS95Apache-2.0

Database snapshot: 13.11.2026 · package version 4a5c1282a957 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100story-author
    Turn a raw feature idea, improvement, or bug description into a structured user story with testable acceptance criteria, persisted as a local markdown file. Invoke when the user wants to create, draft, or refine a story, ticket, requirement, or acceptance criteria — trigger…
  • 100human-requirements
    Use when you need to write software requirement, product specification, system user story, or acceptance criteria
  • 90story-time
    Start the Specify phase of the SPARK loop: the Product Owner interrogates a product idea and turns it into a spec with user stories and testable acceptance criteria. Use when the user brings a new feature idea, product idea or change request that has no spec yet — or wants an…
  • 100requirements-specification
    Use when operator starts a new ticket ("ship X", "build Y", "add feature", "fix workflow") and no spec exists; produces spec, clarify questions, acceptance criteria. Do NOT use for code edits, mid-flight reorgs, or after a spec is locked.
  • 100writing-acceptance-criteria
    Use when a spec document has been approved during brainstorming and you need to produce testable acceptance criteria before writing the implementation plan - converts spec requirements into a structured acceptance criteria document
  • 100specify
    Use when a feature, change, or product idea is still fuzzy and must become an approved WHAT/WHY spec before any planning or code — the brainstorming front door of ASDD stage 2 (Spec). Turns a one-line intent into problem, goals, users, out-of-scope, the four ASDD questions (what…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.