Sheldon Finlay
ce111b4cbe
Planner now has examples for design/UX criteria that are evaluable without being purely binary. Prevents the planner from avoiding qualitative criteria just because they aren't grep-checkable.
47 lines
2.2 KiB
Markdown
47 lines
2.2 KiB
Markdown
# Planner Context
|
|
|
|
This file provides additional context for PRD generation.
|
|
|
|
## Story Decomposition Guidelines
|
|
|
|
When breaking a feature into stories, think about:
|
|
|
|
### Independence
|
|
Each story should be independently deployable. After completing story N, the codebase should be in a valid, working state — even if the feature isn't fully built yet.
|
|
|
|
### Scope
|
|
A story must be completable in a single iteration. Keep each story focused — a handful of files modified, not a sweeping change across the whole codebase. If a story requires reading and modifying more than ~10 files, it's too big — split it.
|
|
|
|
### Failure Isolation
|
|
If a story fails (evaluator rejects it), the next iteration should be able to retry it cleanly. Stories with too many moving parts are hard to retry because partial state is messy.
|
|
|
|
### Evaluability
|
|
Every story must have criteria the evaluator can independently verify by reading code, running commands, or testing behavior.
|
|
|
|
Good criteria are specific and checkable:
|
|
- "Grep for 'HARDCODED_KEY' returns zero matches"
|
|
- "The function returns 404 when the user doesn't exist"
|
|
- "Running `npm test` passes with no failures"
|
|
- "The config file contains entries for all three required env vars"
|
|
|
|
Bad criteria are vague with no way to check:
|
|
- "The code is clean"
|
|
- "Works correctly"
|
|
- "Performance is improved"
|
|
- "Error handling is robust"
|
|
|
|
For subjective work (design, UX, documentation), criteria should define what to evaluate and how to judge it — not just say "looks good":
|
|
- "Design uses a consistent color palette and typography — no default library styles"
|
|
- "A user can complete the primary action without guessing what to click"
|
|
|
|
## PRD Anti-Patterns
|
|
|
|
Avoid these common mistakes:
|
|
|
|
- **Stories too large:** "Build the API" — split into individual endpoints
|
|
- **Stories too small:** "Create the file" — combine with meaningful work in that file
|
|
- **Vague criteria:** "Works correctly" — what does correctly mean? Be specific.
|
|
- **Missing dependencies:** Story 5 needs Story 3's database table but doesn't say so
|
|
- **Testing as afterthought:** Tests should be part of each story, not a separate "add tests" story at the end
|
|
- **UI without backend:** A UI story that calls an API that doesn't exist yet
|