Feature Specification
v1.0.0Convert persona docs into detailed feature specifications with acceptance criteria. Use when translating user needs into implementable specs, writing user stories, defining acceptance criteria, or preparing features for development.
⭐ 0· 1.1k·1 current·1 all-time
by@wpank
Security Scan
OpenClaw
Benign
high confidencePurpose & Capability
Name and description (convert persona docs into feature specs) match the SKILL.md content: templates, user-story guidance, acceptance-criteria patterns, and file path suggestions (docs/personas, docs/specs). There are no unexpected required binaries, env vars, or credentials.
Instruction Scope
Runtime instructions are purely editorial: templates, examples, where to place specs, and how to write stories/acceptance criteria. The skill references local doc paths (e.g., docs/PERSONA.md) which is consistent with its purpose and does not instruct reading unrelated system files or exfiltrating data.
Install Mechanism
The registry contains no install spec (instruction-only), which is low risk. The README suggests using npx or copying from ~/.ai-skills; these are user-run commands and not executed by the platform. Still, running npx against an unknown GitHub/tree URL or a remote package can execute remote code—users should inspect the source before running those commands.
Credentials
No environment variables, credentials, or config paths are requested. The declared scope of data access (persona docs in project folders) is proportionate to the feature-specification purpose.
Persistence & Privilege
always is false and the skill is user-invocable. There is no indication it modifies other skills or requests permanent platform-level privileges.
Assessment
This skill is an editorial template and appears coherent and low-risk. Before installing or running any suggested npx commands: (1) review the source repository or SKILL.md/README content you are about to install, (2) avoid running npx or install commands from untrusted URLs without inspection, and (3) be mindful that persona documents may contain sensitive customer data — avoid sending them to external services. If you want extra assurance, ask the publisher for a canonical repo/homepage or inspect the package contents locally before use.Like a lobster shell, security has layers — review code before you run it.
latest
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.mdordocs/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:
| 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
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:
| 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:
- List all candidate features
- Map each to a persona pain point or journey step
- Assign MoSCoW based on persona impact, not technical interest
- Validate: Do all P0s together form a usable product for the target persona?
- 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:
- Persona docs (
docs/PERSONA.md) — Source of truth for user needs - Feature specs (
docs/specs/) — This skill's output; the development contract - Task creation — Each spec becomes one or more development tasks
- Implementation — Developers reference the spec for scope and criteria
- Testing — QA derives test cases directly from acceptance criteria
- 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
- NEVER write a spec without referencing a persona — every feature exists for a user
- NEVER skip acceptance criteria — "obvious" requirements cause the most bugs
- NEVER use vague qualifiers as requirements — "fast", "easy", "intuitive" are not testable
- NEVER combine multiple features in one spec — one spec, one feature, one clear scope
- NEVER specify implementation details in user stories — describe the what, not the how
- NEVER mark a spec as Approved without edge cases documented — happy paths are the easy part
- NEVER assume dependencies are obvious — list every system, API, feature, and data source the spec relies on
Comments
Loading comments...