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

[zolotokrylin]

DEV-160 tells you how to write a Problem statement but never says what does not deserve to be one. So routine work gets filed as Problems, and 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.

This adds the qualification test to DEV-160 rather than opening a new rule. A clear Problem statement already implies the thing is worth stating as a Problem: if you cannot name an inability, there is nothing to file. Same claim, checkable pass or fail on one subject, so DEV-010's split test does not apply.

What changes:

• A first step in the Solution: confirm the goal is blocked until someone decides or builds something, and if an experienced doer would just do it as part of the work, do it instead of filing it.
• A fourth bad example, Problem: pinned post needs upgrade, alongside the existing technicality and no-actor cases.
• A short paragraph on why micro-chunking costs more than it tracks.
• A matching acceptance criterion.

The Problem statement was trimmed to stay inside DEV-050's 250-character cap, which the rules audit enforces on push.

This came out of a cleanup in holdex/marketing, where one Goal had 23 open sub-issues and 12 of them were routine acts. Three separate open issues asked for the same pinned post to be swapped; one had its Solution checkbox already ticked and had been open since March 2025.

Summary by CodeRabbit

• Documentation
  • Updated Problem-writing guidance to distinguish genuine user or business barriers from routine work.
  • Added barrier-validation criteria and clarified that routine upgrades, such as pinned-post changes, are not valid Problems.
  • Acceptance criteria now require evidence that a goal-blocking barrier exists.

[holdex]

Time Submission Status

Member	#	Time	Running Total	Status	Last Update
zolotokrylin			15min	✅ Submitted	Aug 1, 2026, 7:54 AM

---

Submit or update total time with:

@holdex pr submit-time 2h

Add time on top of previous submission with:

@holdex pr add-time 1h30m

See available commands to help comply with our Guidelines.

[coderabbitai]

Warning

Review limit reached

@zolotokrylin, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 56 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 48b36881-f83d-4c41-a245-67133508af8a

📥 Commits

Reviewing files that changed from the base of the PR and between c97dec5 and fa43fb9.

📒 Files selected for processing (1)

• docs/rules/DEV-160.md

Walkthrough

The Problem-writing guidance now separates user or business barriers from routine work. It adds validation criteria, a routine-work example, and acceptance criteria that require a genuine goal-blocking barrier.

Changes

Problem-writing guidance

Layer / File(s)	Summary
Barrier validation and acceptance criteria docs/rules/DEV-160.md	The guidance explains that technical or routine-work titles do not identify blocked outcomes. It adds barrier-validation steps, a routine-work example, and acceptance criteria for genuine goal-blocking barriers.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

• holdex/developers#123: Both PRs update docs/rules/DEV-160.md; this PR refines guidance introduced by that PR.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main documentation change: file a Problem only when work is blocked.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/rules-problem-qualification

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/rules/DEV-160.md`:
- Line 40: Update the sentence in DEV-160 to use grammatical wording: replace
the “Filing routine acts as Problems…” phrasing with “Filing routine work as
Problems splits the work into micro-chunks.”
- Around line 12-14: Update the explanatory paragraph in DEV-160 by replacing
the claim that “no one can tell when it is resolved” with a precise statement
that “pinned post needs upgrade” fails to identify the user or business outcome
being blocked. Keep the existing examples and prioritization concerns unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 37127a13-5bb3-4fb3-b171-fe248e77f66b

📥 Commits

Reviewing files that changed from the base of the PR and between 0d14176 and c97dec5.

📒 Files selected for processing (1)

• docs/rules/DEV-160.md

[zolotokrylin]

@holdex pr add-time 15m