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]."]

From Issue to Spec

Step 1: Read the issue

gh issue view OWNER/REPO#NUM

Look for: what's the complaint? what does the reporter expect? what's missing?

Step 2: Write the spec

Use the 5-element template above. If you can't fill it in, the issue needs more information — file a comment asking for clarification rather than guessing.

Step 3: Create a task

Record the spec as a task or ticket in your tracking system of choice, with the success_criterion as a first-class field. The binary done/not-done signal from the success criterion is what enables autonomous completion without mid-task re-planning.

Anti-Patterns

Anti-Pattern	Fix
"I'll figure out the scope as I go"	Figure out the scope before you start. Scope discovered mid-implementation causes rework.
"The issue title is clear enough"	Issue titles describe the symptom. Acceptance criteria describe what done looks like. These are different.
"I'll add acceptance criteria to the PR"	PR acceptance criteria are retrospective. Spec first, then implementation, then PR.
"This is small, I don't need a spec"	If it's small enough to skip a spec, it's small enough to write the spec in 3 minutes. Do it.
"The issue has a lot of comments, I'll read them later"	Read them now. The thread often contains the acceptance criteria, edge cases, and out-of-scope decisions already worked out.
Implementing everything in the issue	Issues are wishlists. Specs are commitments. Pick the minimum slice that closes the issue.

Red Flags (spec is insufficient)

• Acceptance criteria use words like "better", "improved", "faster" without a measurable threshold
• No explicit out-of-scope list (scope creep guaranteed)
• Success criterion references "user will be happy" — not testable
• Spec lists 8+ acceptance criteria (too big for one task; break it down)
• Edge cases section is empty (they exist; you just haven't thought about them)

Outcome

A good spec:

• Prevents starting the wrong thing
• Enables autonomous completion without mid-task re-planning
• Creates clear done/not-done signal for the success criterion field
• Reduces PR review churn (reviewer and author agree on scope upfront)
• Makes parallel agent sessions safe (clear scope = no convergent duplicate work)