specification

Facilitates one-question-at-a-time specification conversations that produce example maps and acceptance criteria.

Updated May 18, 2024
One-click install
npx skills add https://github.com/joshhornby/dotfiles --skill specification-joshhornby
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: specification
Source: https://github.com/joshhornby/dotfiles/tree/main/.claude/skills/specification
Command: npx skills add https://github.com/joshhornby/dotfiles --skill specification-joshhornby

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and assets (resource) components.

What problem does it solve? Fuzzy feature ideas and problem statements often jump straight into planning or coding without agreed rules, leading to rework and misaligned expectations. This Skill forces a structured conversation that turns vague intent into shared understanding, concrete examples, and acceptance criteria before any story is split or planned. ## Core Features & Use Cases - Example Mapping: Builds a live map of story, rules, concrete examples, and open questions, written back into the team's existing story artifact (issue, ticket, or docs file). - Accountable Review Rounds: Generates a self-contained HTML review page from a template so owners and risk-relevant stakeholders can annotate rules, parked questions, and candidate vocabulary, with feedback routed back as answers rather than silent edits. - Readiness Diagnostics: Reads the map's shape to decide next steps — question-dominated maps keep the conversation going, rule-dominated maps go to story-splitting, balanced maps are ready to build. - Use Case: A product owner says "users should be able to pause subscriptions." The Skill asks one question at a time, captures rules like "paused subscriptions retain history" with concrete examples, parks unresolved billing questions with owners and dates, and produces acceptance criteria plus a review page for the team. ## Quick Start Ask the agent to spec out a new feature idea by running one question at a time and writing the resulting example map and acceptance criteria into the story's existing artifact.

Frequently Asked Questions about specification

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I turn a vague feature idea into acceptance criteria?

Run a specification conversation that asks one question at a time, capturing each business rule with concrete examples in an example map. Once examples stabilize, distill them into acceptance criteria written back into the story's existing artifact, then have the accountable owner review them.

What is example mapping in agile specification?

Example mapping structures a story as rules, concrete examples, and open questions. The map's shape acts as a diagnostic: question-dominated means not ready to build, rule-dominated means the story is too big and needs splitting, and balanced maps with concrete examples are ready.

When should I use specification versus story-splitting?

Use specification first, when an idea has no agreed rules or examples yet. Once the example map stabilizes but contains more than roughly six rules, hand it to story-splitting to slice the agreed work into child stories that carry their rules and examples onward.

How does the specification review page work?

The Skill fills a self-contained HTML template with the map's rules, parked questions, and candidate vocabulary as annotatable cards, then opens it locally for reviewers. Feedback is copied as markdown and returned to the next conversation round as answers and new questions, never as silent edits.

What are the limitations of agent-facilitated specification?

The agent-facilitated round produces only a first draft of shared understanding. It becomes usable only after the accountable owner and, where risk warrants, business, development, and testing perspectives review it; acceptance criteria remain hypotheses until the shipped slice confirms them.