Feature Specification (Meta-Skill)

Bridge persona documentation and development. This skill translates user needs, pain points, and journeys identified in persona docs into structured, implementable feature specifications with clear acceptance criteria.

Installation

OpenClaw / Moltbot / Clawbot

CODEBLOCK0

---

Purpose

Persona docs define who and why. Feature specs define what and how well. This skill closes the gap:

• - Extracts actionable features from persona pain points and journeys
• Structures requirements so developers know exactly what to build
• Defines acceptance criteria so QA knows exactly what to verify
• Prevents scope ambiguity before a single line of code is written

---

When to Use

• - After persona docs exist (docs/PERSONA.md or docs/personas/)
• Before development begins on a new feature or product
• When a feature request lacks clear acceptance criteria
• When stakeholders disagree on what "done" means
• When converting user feedback into development work

---

Feature Spec Template

Use this structure for every feature specification. Place specs in docs/specs/ or docs/features/.

CODEBLOCK1

---

Writing Effective User Stories

User stories connect persona needs to developer tasks. Apply the INVEST criteria:

Criterion	Meaning	Test Question
Independent	No ordering dependency on others	Can this be built and released alone?
Negotiable

Details can be discussed | Is this a conversation starter, not a contract? |
| Valuable | Delivers value to the persona | Would the persona care about this? |
| Estimable | Team can estimate effort | Is the scope clear enough to size? |
| Small | Fits in a single iteration | Can this ship in one sprint? |
| Testable | Clear pass/fail verification | Can QA write a test for this? |

Good vs Bad User Stories

Bad	Why It's Bad	Good
"Users can log in"	No persona, no benefit	"As a returning customer, I want to log in with my email, so that I can access my order history"
"Make it fast"

Vague, untestable | "As a mobile user on 3G, I want the product list to load in under 2s, so that I don't abandon the page" | | "Add admin panel" | Solution-first, no problem | "As a store manager, I want to update product prices without developer help, so that I can respond to market changes daily" | | "Handle errors" | No specificity | "As a checkout user, I want clear feedback when my payment fails, so that I know whether to retry or use a different card" | | "Implement caching" | Implementation detail, not a story | "As a repeat visitor, I want previously viewed pages to load instantly, so that browsing feels responsive" |

---

Acceptance Criteria Patterns

Pattern 1: Happy Path

CODEBLOCK2

Pattern 2: Boundary Conditions

CODEBLOCK3

Pattern 3: Error Cases

CODEBLOCK4

Pattern 4: State Transitions

CODEBLOCK5

Pattern 5: Negative / Security

CODEBLOCK6

---

Priority Framework

Apply MoSCoW prioritization, anchored to persona impact:

Priority	Label	Definition	Persona Alignment
P0	Must	Product is unusable without this	Blocks the persona's primary goal
P1

Should | Significant value, painful to defer | Addresses a top-3 pain point |
| P2 | Could | Nice to have, enhances experience | Improves a secondary journey |
| P3 | Won't | Explicitly deferred (this release) | Low-frequency need or niche scenario |

Prioritization process:

1. 1. List all candidate features
2. Map each to a persona pain point or journey step
3. Assign MoSCoW based on persona impact, not technical interest
4. Validate: Do all P0s together form a usable product for the target persona?
5. Cut scope until P0s are achievable in the timeline

---

Specification Anti-Patterns

Anti-Pattern	Example	Fix
Vague requirement	"System should be user-friendly"	Define measurable criteria: "Task completion in < 3 clicks"
Missing edge cases

Only specifying the happy path | Add boundary, error, and concurrent-use scenarios | | No acceptance criteria | "Implement search" | Add Given/When/Then for each scenario | | Solution masquerading as need | "Use Redis for caching" | State the need: "Repeat queries return in < 50ms" | | Missing personas | "Users can export data" | Specify which persona and why they export | | Unbounded scope | "Support all file formats" | List exact formats: "PDF, CSV, XLSX" | | Implicit assumptions | Assuming auth exists without stating it | List all dependencies explicitly |

---

Integration with Workflow

Feature specs connect to the broader development process:

1. 1. Persona docs (docs/PERSONA.md) — Source of truth for user needs
2. Feature specs (docs/specs/) — This skill's output; the development contract
3. Task creation — Each spec becomes one or more development tasks
4. Implementation — Developers reference the spec for scope and criteria
5. Testing — QA derives test cases directly from acceptance criteria
6. Review — PR reviews check that acceptance criteria are met

When using with the /new-feature command or similar workflows:

• - Read the relevant persona doc first
• Generate the spec using this template
• Validate acceptance criteria cover happy path, errors, and edge cases
• Confirm priority with stakeholders before development begins

---

NEVER Do

1. 1. NEVER write a spec without referencing a persona — every feature exists for a user
2. NEVER skip acceptance criteria — "obvious" requirements cause the most bugs
3. NEVER use vague qualifiers as requirements — "fast", "easy", "intuitive" are not testable
4. NEVER combine multiple features in one spec — one spec, one feature, one clear scope
5. NEVER specify implementation details in user stories — describe the what, not the how
6. NEVER mark a spec as Approved without edge cases documented — happy paths are the easy part
7. NEVER assume dependencies are obvious — list every system, API, feature, and data source the spec relies on