Skip to content

docs(rules): file a Problem only when work is actually blocked #137

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zolotokrylin merged 2 commits into from
Aug 1, 2026
Merged

docs(rules): file a Problem only when work is actually blocked #137

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c97dec5
docs(rules): file a Problem only when work is actually blocked
zolotokrylin Aug 1, 2026
fa43fb9
docs(rules): read the Problem statement rule without stumbling
zolotokrylin Aug 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 19 additions & 4 deletions docs/rules/DEV-160.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Loading