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

npx clawhub@latest install feature-specification

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/.

# Feature: [Feature Name]

## Metadata
- **Priority:** [Must / Should / Could / Won't]
- **Target Persona:** [Persona name from persona docs]
- **Status:** Draft | Review | Approved | In Progress | Complete
- **Estimated Effort:** [T-shirt size: XS / S / M / L / XL]

## Problem Statement
[Directly reference the persona pain point this feature addresses.
Quote or link to the relevant section of persona docs.]

## Solution Description
[High-level description of what the feature does and how it solves
the problem. 2-4 sentences. No implementation details.]

## User Stories

- As a [persona], I want [action], so that [benefit].
- As a [persona], I want [action], so that [benefit].

## Acceptance Criteria

### Scenario: [Happy path description]
- **Given** [precondition]
- **When** [action]
- **Then** [expected result]

### Scenario: [Alternative path description]
- **Given** [precondition]
- **When** [action]
- **Then** [expected result]

### Scenario: [Error case description]
- **Given** [precondition]
- **When** [invalid action]
- **Then** [error handling result]

## Edge Cases
- [ ] [Edge case 1 — description and expected behavior]
- [ ] [Edge case 2 — description and expected behavior]

## Non-Functional Requirements
- **Performance:** [Response time, throughput, load targets]
- **Accessibility:** [WCAG level, keyboard nav, screen reader support]
- **Security:** [Auth requirements, data sensitivity, input validation]
- **Browser/Device:** [Support matrix]

## Dependencies
- [Feature or system this depends on]
- [External API or service required]

## Out of Scope
- [Explicitly list what this feature does NOT include]
- [Prevents scope creep during development]

## Design References
- [Link to mockups, wireframes, or design system components]
- [Screenshots or diagrams if available]

Writing Effective User Stories

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

Good vs Bad User Stories

Acceptance Criteria Patterns

Pattern 1: Happy Path

Given a logged-in customer with items in their cart
When they click "Checkout"
Then they are taken to the payment page with their cart summary visible

Pattern 2: Boundary Conditions

Given a cart with 100 items (maximum allowed)
When the user tries to add another item
Then they see "Cart limit reached — remove an item to add a new one"
And the item is NOT added to the cart

Pattern 3: Error Cases

Given a user submitting the registration form
When the email field contains "not-an-email"
Then the form shows inline validation: "Enter a valid email address"
And the form is NOT submitted
And focus moves to the email field

Pattern 4: State Transitions

Given an order with status "Processing"
When the warehouse marks it as shipped
Then the order status changes to "Shipped"
And the customer receives a shipping confirmation email within 5 minutes
And the tracking number is visible on the order detail page

Pattern 5: Negative / Security

Given a user who is NOT the account owner
When they attempt to access /account/settings via direct URL
Then they receive a 403 Forbidden response
And the access attempt is logged

Priority Framework

Apply MoSCoW prioritization, anchored to persona impact:

Prioritization process:

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

Integration with Workflow

Feature specs connect to the broader development process:

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