diff --git a/docs/rules/DEV-160.md b/docs/rules/DEV-160.md index ea9005f..1e2e50c 100644 --- a/docs/rules/DEV-160.md +++ b/docs/rules/DEV-160.md @@ -9,14 +9,20 @@ depends_on: ["DEV-150"] ## Problem -A Problem titled "missing balance API" or "CSV export missing" tells a -stakeholder nothing about what a user cannot do. It cannot be prioritized, and -no one can tell when it is resolved. +A Problem titled "missing balance API" or "pinned post needs upgrade" tells a +stakeholder nothing about what a user cannot do. Neither names the user or +business outcome being blocked, so neither can be prioritized. ## Solution -Write each Problem so a non-technical stakeholder understands it at a glance. +Write each Problem so a non-technical stakeholder understands it at a glance. If +you cannot state an inability, there is nothing to file: routine work an +experienced person would simply do is process, not a barrier, and belongs in the +work itself. +1. Confirm it is a barrier. Ask whether the goal is blocked until someone + decides or builds something. If an experienced doer would just do it as part + of the work, do it instead of filing it. 1. Title it `Problem: [statement]`, under 65 characters. 1. State what the user or business cannot do, in plain terms, not the solution's technicalities. @@ -28,11 +34,20 @@ Write each Problem so a non-technical stakeholder understands it at a glance. Good: Problem: operators can't view their account balance Bad: Problem: missing balance API (a technicality, not a user problem) Bad: Problem: CSV export missing (no actor, no action) +Bad: Problem: pinned post needs upgrade (routine work, not a barrier) ``` +Filing routine work as Problems splits the work into micro-chunks. Each one adds +an issue to track, a notification on every PR that touches it, and a status +nobody updates, while tracking nothing that was ever blocked. Three open issues +asking for a pinned post to be swapped are not three barriers; they are one +unperformed task. + ### Acceptance Criteria - [ ] The title is `Problem: ...`, under 65 characters +- [ ] It names a barrier that blocks the goal, not routine work a doer would + simply perform - [ ] It states a user or business inability, not a solution technicality - [ ] A non-technical stakeholder can understand it - [ ] It is a sub-issue of the Goal and has a Problem and a Solution section