papi-sdlc-user-stories

Files (3)

• SKILL.md
• user-stories-template.md · assets/
• user-story-template.md · assets/

SKILL.md (first lines)

# SDLC Task - User Stories

## When to use this skill

Use this skill whenever a unit of product or system behaviour needs to be
captured from the perspective of a specific actor — whether for backlog
grooming, epic decomposition, or as the specification source for a development
or component task.

## When to use this skill (continued)

- Read, copy and use the appropriate template.
- Create the parent document first if one does not yet exist for the product/epic.
- Each individual story document links back to its parent, and the parent indexes all child stories.

## Dependencies

Reading these skills is REQUIRED to understand and execute this skill:

- PAPI skill `papi-sdlc-understand`
- PAPI skill `papi-templates-understand`

## Core principles

### One story, one actor, one goal

A user story describes a single outcome for a single role. If the narrative
requires more than one actor or more than one goal, split it into separate
stories. Compound stories indicate unclear scope and produce untestable
acceptance criteria.

### Specific roles, not "user"

The actor must identify a real, distinguishable role with distinct needs
(e.g., "authenticated administrator", "background job scheduler",
"third-party API consumer"). Generic actors like "user" or "system" are
not acceptable — they obscure who actually benefits and make the story
harder to prioritise and validate.

### Goals state *what*, not *how*

The "I want to" clause must describe a goal, not an implementation. If the
narrative specifies a UI control, an API endpoint, or an algorithm, it has
crossed into solution space. Reserve implementation decisions for the
development or component task that fulfils the story.

### Falsifiable benefit

The "so that" clause must describe an outcome that can be confirmed or
refuted through the interface described in the story. If the benefit cannot
be observed or measured, it is not a valid acceptance criterion anchor and
the story needs to be rewritten.

### Interface before criteria

Before writing acceptance criteria, the Interface section must clearly
describe how the actor initiates the interaction and what observable
response or state change they receive. Acceptance criteria must assert
outcomes expressed in terms of that interface — not internal system state
or implementation details.

### Negative and boundary cases are required

Every story must include at least one acceptance criterion covering a
negative case (e.g., invalid input, unauthorised access, resource not found)
or a boundary condition. Stories with only happy-path criteria are
incomplete.

### Stories are not tasks, and carry no evidence

A user story is a specification artefact, not a work item. Once a story
reaches **Ready** status, one or more development or component tasks are
created to fulfil it. The story remains as the authoritative statement of
intent and is linked from those tasks.

The story document must not contain implementation notes, test results,
fulfilment status, or audit findings. Those belong in task, testing,
release, or audit artefacts. The story's only lifecycle signal is its
**Status** field.

### Stories know nothing about component specifications

A user story is an upstream statement of intent and MUST NOT reference
component specifications, capability codes, or any other solution
structure. The dependency points the other way: the user-facing
components that fulfil a story reference *it* from their capability
`**Users:**` fields (see the `papi-sdlc-component-specification` skill),
never the reverse. This keeps stories stable when the architecture is
refactored.

### Stories are written in the actor's language

Narrative, interface, and acceptance criteria must use vocabulary the
named role would actually use. Reviewer check: would this role read the
story and recognise their own world? If not, rewrite.

### Status reflects scope

A story's **Status** must be consistent with the scope of its parent
epic/release. Stories outside current scope stay **Draft** (or are
removed). Do not mark a story **Ready** unless its scope agrees with
that of its parent epic/release.

## Checklist when creating a user story

- [ ] ID assigned (unique within the epic or backlog)
- [ ] Actor is specific and distinguishable — not "user" or "system"
- [ ] Goal states what the actor achieves, not how the system implements it
- [ ] Benefit is falsifiable — it can be confirmed through the interface
- [ ] Interface section describes the observable interaction and response
- [ ] At least two acceptance criteria written in Given / When / Then form
- [ ] At least one negative or boundary acceptance criterion included
- [ ] All criteria are assertable through the interface, not internal state
- [ ] Story contains exactly one actor and one primary goal (split if not)
- [ ] `**Role:**` field set, matches the narrative actor, and matches a role defined in the parent user-stories document
- [ ] Story body is free of capability codes and component-spec references
- [ ] Wording uses language the named role would recognise
- [ ] No implementation / test / fulfilment / audit evidence in story body
- [ ] Status (Draft / Ready / In Progress / Done) matches parent scope

From stainsby/papi, MIT.

More from stainsby/papi