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.
2.2 KiB
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 testpasses 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