Five-Element Spec: Scope Before Coding

Five-Element Spec: Scope Before Coding

Translate a vague request or GitHub issue into a concrete, actionable spec before writing any code.

Core principle: If you can't write down what "done" looks like in two sentences, you're not ready to start.

The five-element spec is a lightweight planning format that forces explicit scope boundaries, testable acceptance criteria, and a binary done/not-done signal. It takes 5 minutes for small tasks and prevents hours of rework from scope mismatches, PR churn, and "I thought we wanted X" surprises.

When to Use

Always before:

• Starting work on a GitHub issue that hasn't been scoped into a task
• Implementing a feature where acceptance criteria aren't obvious
• Any task that will take >30 minutes (if you can't spec it in 5 minutes, the scope is unclear)
• Work that will produce a PR (scope ambiguity creates PR churn)

Skip for:

• Bug fix with a clear reproduction path and obvious scope
• Mechanical tasks (update a config value, rename a symbol, bump a version)
• Work already described in a task with a success_criterion field

Installation

Claude Code

cp -R skills/five-element-spec ~/.claude/skills/five-element-spec

Invoke with /five-element-spec before starting any non-trivial implementation task.

Direct repo/manual install

git clone https://github.com/agentskillexchange/skills.git
cp -R skills/five-element-spec ~/.agent-skills/five-element-spec

The 5-Element Spec

A complete spec answers five questions:

1. PROBLEM — What is broken or missing? What pain does this cause?
2. SCOPE — What is in scope? What is explicitly out of scope?
3. ACCEPTANCE CRITERIA — What must be true when this is done? (testable)
4. EDGE CASES — What unusual inputs or states must be handled?
5. SUCCESS CRITERION — One sentence: how will we know it's done?

Spec Template

## Problem
[1-2 sentences: what is broken/missing and why it matters]

## Scope
**In scope:**
- [Specific thing 1]
- [Specific thing 2]

**Out of scope (explicitly):**
- [Thing someone might expect but we're not doing]

## Acceptance Criteria
- [ ] [Testable condition 1 — "X works when Y" or "CI passes for Z"]
- [ ] [Testable condition 2]
- [ ] [Testable condition 3]

## Edge Cases
- [Input or state that needs explicit handling]
- [Boundary condition]

## Success Criterion
[One sentence. "When [action], [outcome] happens, verified by [test/check]."]