Idea To Spec

Overview

Vague ideas produce vague implementations. This skill transforms any idea — no matter how fuzzy — into a concrete specification with clear scope, acceptance criteria, and non-goals.

When to Use

• At the start of any new feature
• When a request is ambiguous
• Before creating tasks or writing any code

Process

Step 1: Capture the Core Problem

1. Write: "Users currently can't [do X], which causes [pain Y]."
2. Identify: who has this problem? How often? What's the impact?
3. Distinguish problem from solution — don't spec a solution until the problem is understood.

Verify: You can state the problem without mentioning any implementation.

Step 2: Define Success

1. Write 3–7 acceptance criteria in this format:

`` Given [context] When [action] Then [outcome] ``

1. Each criterion must be binary — either it passes or it doesn't.
2. Include negative cases: "Given X, the system must NOT do Y."

Verify: A QA engineer can test each criterion without asking for clarification.

Step 3: Define Scope

1. In scope: List what is explicitly included.
2. Out of scope: List what is explicitly excluded — as important as what's included.
3. Open questions: List any decisions that still need resolution before implementation.

Verify: The out-of-scope list has at least 2 items.

Step 4: Define Non-Functional Requirements

1. Performance: response time, throughput, scale targets.
2. Security: auth requirements, data sensitivity.
3. Reliability: uptime SLA, acceptable error rate.

Verification

• [ ] Problem statement written without mentioning implementation
• [ ] Acceptance criteria in Given/When/Then format
• [ ] Each criterion is binary (pass/fail)
• [ ] Explicit out-of-scope list
• [ ] Open questions listed

References

• [think-before-coding skill](../think-before-coding/SKILL.md)
• [task-decomposition skill](../task-decomposition/SKILL.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DevelopersGlobal
• Source: DevelopersGlobal/ai-agent-skills
• License: MIT
• Homepage: https://developersglobal.github.io/ai-agent-skills/

Install and usage instructions live in the source repository linked above.