DEV-160: Write a Problem Issue Stakeholders Can Act On

Problem

A Problem titled "missing balance API" names no user and no outcome, so it cannot be prioritized. Its Solution section drifts the same way, arriving as a list of steps to perform, so a reviewer cannot tell what the business gains when it merges.

Solution

Write each Problem so a non-technical stakeholder understands it at a glance. The issue carries the pain and the direction. How to execute belongs to the pull request that resolves it, per DEV-170.

Both halves fail the same way. A title that names a missing artifact, and a Solution that lists accounts to provision and READMEs to update, describe steps performed rather than outcome delivered, which is what DEV-440 says not to do. Length is what lets it happen: given room, the inability and the outcome end up buried under execution detail. The caps below take the room away.

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.
2. Title it Problem: [statement], under 65 characters.
3. State what the user or business cannot do, in plain terms, not the solution's technicalities. Keep it within the Problem cap in DEV-050.
4. Open the # Solution section with one sentence naming what the user or business can do once this merges. Any recommended direction follows that sentence. Keep the Solution prose to 450 characters or fewer.
5. Open it as a sub-issue of the Goal and link the Goal in the description.

Both caps count prose only. Importance, urgency, and priority lines, the references list, and links do not count against them. They are deliberately tight: at that length there is no room for implementation steps, which is the point. Detail that does not fit was never the statement, it was the execution, and it belongs in the pull request.

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)

For the Solution's opening sentence:

Good:  The platform stays reachable under attack and our servers cannot be
       targeted directly.
Bad:   Put both domains behind Cloudflare and accept origin traffic only from
       Cloudflare.               (a provisioning step, not an outcome)

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.

Both caps are machine-checkable, and the Problem cap already is: the rules audit enforces DEV-050 on every rule file it checks. On issues the reviewer checks them, until the bot does.

The parent is checked by the bot already. Half an hour after a Problem is opened, reopened, retitled, retyped or changes parent, or after its Goal is closed, Wizard comments on it if it is still open and not a sub-issue of an open Goal. The comment goes away once the Problem is under an open Goal or closed.

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
• The Problem prose is within the cap in DEV-050
• The Solution's first sentence states what the user or business can do once this merges
• The Solution prose is 450 characters or fewer
• A non-technical stakeholder understands both sections without asking a follow-up
• It is a sub-issue of the Goal and has a Problem and a Solution section