User Stories
The user has finished building a project but is not confident it behaves the
way they think it does. Go through it together using user stories, so you can
(1) spell out what a user can actually do, (2) find edge cases, and (3)
reconcile their mental model with what is actually built, fixing anything
that is wrong.
Ground rules
- The code is the source of truth for what the system DOES. The user is the
source of truth for what it SHOULD do. Never assume intent; if unsure, ask.
- Write stories from the user's point of view (what they see, do, and get
back), not in terms of functions or classes. Cite file paths and lines for
where each behavior lives.
- If you cannot tell how something behaves from reading the code, say so
instead of guessing, and offer to run it or write a quick test to find out.
- Do not change any code until the user approves a specific fix. Do not
refactor unrelated code.
- Keep a running record in
docs/user-stories.md (create it if missing). If
it already exists, read it first and resume where you left off.
Phase 1: Map the project (no code changes)
Explore the repo: README, entry points, routes/pages/screens, API endpoints,
CLI commands, background jobs, data models, auth/permissions, config, and
existing tests. Then give the user:
- What kind of project this is and how a user interacts with it.
- User roles: every distinct actor (guest, logged-in user, admin, API
client, scheduled job, external service).
- Feature map: features/flows grouped logically, each with a one-line
description, its main files, and which roles use it.
- Red flags: half-built features, TODOs, dead code, backend features with no
way to reach them from the UI (or the reverse), and inconsistencies between
features.
Then stop and ask the user which feature to start with.
Phase 2: One feature at a time
For the feature the user picks:
Step 1: Draft stories from the code
For each story:
- "As a [role], I want to [action], so that [outcome]."
- Acceptance criteria (Given / When / Then) describing what the code
ACTUALLY does, with file references.
- Edge cases, each marked handled / not handled / unclear, with what actually
happens. Consider: empty, invalid, or extreme input; missing permissions or
unauthenticated access; double-submit and concurrent edits; network or
third-party failures; partial failure mid-flow; items deleted, expired, or
changed by someone else; first-time vs returning user; large data; dates
and time zones; plus anything specific to this project.
Work the edge cases adversarially (see interrogate): a finding survives
only when a run proves it. Do not claim an edge case is handled because the
code looks right; run it, or mark it unclear. For anything about why the
code is shaped the way it is, investigate the rationale with cited evidence
(see why) instead of guessing.
Step 2: Review with the user ONE story at a time
Show the story, what actually happens, and its edge cases, then ask: "Is
this what you intended?" The user answers yes, no (and explains what they
meant), or not sure. If they are not sure, help them decide by laying out
the trade-offs. Do not move on until the current story is settled.
Step 3: Handle mismatches
When the user says the behavior is wrong:
- Log it: expected vs actual, where in the code, severity (breaks things /
wrong but harmless / cosmetic).
- Propose a fix: which files change, the approach, and which other stories or
features it could affect. Check the blast radius first (see
blast-radius): what else could this change break, and prove the one fact
it is safe because of by running code. If what the user wants conflicts
with another story or creates a new edge case, say so.
- Wait for approval, then make the change.
Step 4: Tests
- For each confirmed story, write tests for its acceptance criteria and key
edge cases, following the project's existing test framework and
conventions. Tests assert what the code's users can observe, so a test
fails when the behavior breaks and keeps passing when only the internals
change: drive the code through its users' interface with a concrete input,
derive the expected value from the requirement, not from a run of the code.
- For each fix, write a regression test first (see
tdd), confirm it fails
on the old behavior, then make the fix and confirm it passes.
- If the project has no test setup, propose a minimal one and ask before
adding it.
- Run the relevant tests and report the results.
Step 5: Wrap up the feature
Update docs/user-stories.md with the stories (status: confirmed / changed /
open), the mismatch log, tests added, and open questions. Give the user a
short summary, then ask which feature to do next.
Provenance
Authored from the user's own prompt (2026-11-13). Edge-case discipline
adapted from cursor/plugins pstack/interrogate and pstack/why,
regression-test-first from pstack/tdd, behavior-not-implementation test
rule from pstack/principle-test-behavior-not-implementation, blast-radius
check from pstack/blast-radius (all MIT).
1---2name: user-stories3description: >-4 Review a finished project with the user through user stories: map what a5 user can actually do, find edge cases, and reconcile the user's mental model6 with what the code really does, fixing mismatches with their approval. Use7 when the user says user stories, review this project, is this what I built,8 or wants a second pass over a somewhat-done project before polishing it.9license: MIT10metadata:11 source: https://skillmd.com/skills/hongyime/user-stories12 author: Local setup13 version: "1.0.0"14 platform: "Codex, Antigravity (agy), OpenCode, Muse on Windows, macOS, Linux (Debian)"15---1617# User Stories1819The user has finished building a project but is not confident it behaves the20way they think it does. Go through it together using user stories, so you can21(1) spell out what a user can actually do, (2) find edge cases, and (3)22reconcile their mental model with what is actually built, fixing anything23that is wrong.2425## Ground rules2627- The code is the source of truth for what the system DOES. The user is the28 source of truth for what it SHOULD do. Never assume intent; if unsure, ask.29- Write stories from the user's point of view (what they see, do, and get30 back), not in terms of functions or classes. Cite file paths and lines for31 where each behavior lives.32- If you cannot tell how something behaves from reading the code, say so33 instead of guessing, and offer to run it or write a quick test to find out.34- Do not change any code until the user approves a specific fix. Do not35 refactor unrelated code.36- Keep a running record in `docs/user-stories.md` (create it if missing). If37 it already exists, read it first and resume where you left off.3839## Phase 1: Map the project (no code changes)4041Explore the repo: README, entry points, routes/pages/screens, API endpoints,42CLI commands, background jobs, data models, auth/permissions, config, and43existing tests. Then give the user:44451. What kind of project this is and how a user interacts with it.462. User roles: every distinct actor (guest, logged-in user, admin, API47 client, scheduled job, external service).483. Feature map: features/flows grouped logically, each with a one-line49 description, its main files, and which roles use it.504. Red flags: half-built features, TODOs, dead code, backend features with no51 way to reach them from the UI (or the reverse), and inconsistencies between52 features.5354Then stop and ask the user which feature to start with.5556## Phase 2: One feature at a time5758For the feature the user picks:5960### Step 1: Draft stories from the code6162For each story:6364- "As a [role], I want to [action], so that [outcome]."65- Acceptance criteria (Given / When / Then) describing what the code66 ACTUALLY does, with file references.67- Edge cases, each marked handled / not handled / unclear, with what actually68 happens. Consider: empty, invalid, or extreme input; missing permissions or69 unauthenticated access; double-submit and concurrent edits; network or70 third-party failures; partial failure mid-flow; items deleted, expired, or71 changed by someone else; first-time vs returning user; large data; dates72 and time zones; plus anything specific to this project.7374Work the edge cases adversarially (see `interrogate`): a finding survives75only when a run proves it. Do not claim an edge case is handled because the76code looks right; run it, or mark it unclear. For anything about why the77code is shaped the way it is, investigate the rationale with cited evidence78(see `why`) instead of guessing.7980### Step 2: Review with the user ONE story at a time8182Show the story, what actually happens, and its edge cases, then ask: "Is83this what you intended?" The user answers yes, no (and explains what they84meant), or not sure. If they are not sure, help them decide by laying out85the trade-offs. Do not move on until the current story is settled.8687### Step 3: Handle mismatches8889When the user says the behavior is wrong:9091- Log it: expected vs actual, where in the code, severity (breaks things /92 wrong but harmless / cosmetic).93- Propose a fix: which files change, the approach, and which other stories or94 features it could affect. Check the blast radius first (see95 `blast-radius`): what else could this change break, and prove the one fact96 it is safe because of by running code. If what the user wants conflicts97 with another story or creates a new edge case, say so.98- Wait for approval, then make the change.99100### Step 4: Tests101102- For each confirmed story, write tests for its acceptance criteria and key103 edge cases, following the project's existing test framework and104 conventions. Tests assert what the code's users can observe, so a test105 fails when the behavior breaks and keeps passing when only the internals106 change: drive the code through its users' interface with a concrete input,107 derive the expected value from the requirement, not from a run of the code.108- For each fix, write a regression test first (see `tdd`), confirm it fails109 on the old behavior, then make the fix and confirm it passes.110- If the project has no test setup, propose a minimal one and ask before111 adding it.112- Run the relevant tests and report the results.113114### Step 5: Wrap up the feature115116Update `docs/user-stories.md` with the stories (status: confirmed / changed /117open), the mismatch log, tests added, and open questions. Give the user a118short summary, then ask which feature to do next.119120## Provenance121122Authored from the user's own prompt (2026-11-13). Edge-case discipline123adapted from cursor/plugins `pstack/interrogate` and `pstack/why`,124regression-test-first from `pstack/tdd`, behavior-not-implementation test125rule from `pstack/principle-test-behavior-not-implementation`, blast-radius126check from `pstack/blast-radius` (all MIT).