docs(rules): read a Problem and know what the business gains

[zolotokrylin]

A stakeholder can open any Problem issue and, in two short sections, see what the business cannot do today and what it will be able to do once the work merges, without reading implementation detail.

DEV-160 already held the Problem statement to a business inability, but nothing held the Solution section to the same bar, so it came back as a list of steps to perform. Length was what allowed it: given room, the inability and the outcome ended up buried under execution detail that belongs to the PR.

What changed

• DEV-050 becomes the canonical home for the Problem length cap and now governs any Problem statement, whether it is the ## Problem of a rule file or the # Problem of a Problem issue. A rule is a Problem too; it is a rule only because the barrier recurs on the ops side instead of in the product, which does not change what its statement has to do. Severity moves from warning to error.
• DEV-160 requires the Solution to open with one sentence naming what the user or business can do once the work merges, and caps the Solution prose at 450 characters. It defers to DEV-050 for the Problem cap rather than restating a number. Retitled to name the single behavior it enforces.
• DEV-360 holds the PR description to the same outcome-first bar, since the gap showed up in PR bodies too, not only in issues.
• docs/rules/README.md index follows the retitle.

Notes for the reviewer

• One cap, 250 characters, defined once. scripts/check-rules.mjs already hardcoded PROBLEM_MAX = 250 and credited DEV-050 as its source, so the audit needed no change and the severity bump just makes the frontmatter honest about the push being blocked.

• The 450-char Solution cap stays local to DEV-160. A rule file's Solution carries method and reasoning and is deliberately long; a Problem issue's states an outcome. Different subjects, so no shared number.

• The caps are deliberately tight. At 250 characters there is no room for implementation steps, which is the point. Detail that does not fit was never the statement, it was the execution.

• Enforcement on issues stays manual. The Problem cap is already automated for rule files.

• DEV-050 applies to the rule files edited here. Both Problem sections were brought under 250, and npm run check:rules passes across all 35 rules.

• Closes Problem: reviewers can't tell if a Solution delivers an outcome #141

Summary by CodeRabbit

• Documentation
  • Updated contribution guidance to prioritize actionable Problem issues and clearly stated user or business outcomes.
  • Clarified character limits and content requirements for Problem and Solution sections.
  • Strengthened guidance to distinguish outcomes from implementation details.
  • Raised DEV-050 severity from warning to error and expanded its scope to relevant Problem sections.
  • Updated examples and acceptance criteria to reflect the revised requirements.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: db68bca7-f24b-49e8-830b-7916ed1fca6e

📥 Commits

Reviewing files that changed from the base of the PR and between 98a8e84 and 13a48da.

📒 Files selected for processing (4)

• docs/rules/DEV-050.md
• docs/rules/DEV-160.md
• docs/rules/DEV-360.md
• docs/rules/README.md

---

Walkthrough

Changes

Outcome-focused rule guidance

Layer / File(s)	Summary
Problem section limits and scope docs/rules/DEV-050.md	DEV-050 severity is now error. Its character-limit requirements apply to rule-file Problem sections and DEV-160 Problem issues.
Actionable Problem and Solution requirements docs/rules/DEV-160.md, docs/rules/README.md	DEV-160 requires explicit barriers and outcomes, limits Problem and Solution prose, and requires Solutions to begin with the post-merge outcome.
Outcome-first pull request descriptions docs/rules/DEV-360.md	DEV-360 requires Problem and pull request descriptions to lead with user or business outcomes instead of implementation edits.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• holdex/developers#123: Updates DEV-160 with related outcome-focused Problem and Solution guidance.
• holdex/developers#137: Modifies DEV-160’s Problem-writing guidance and acceptance criteria.
• holdex/developers#124: Updates DEV-050 and DEV-360 with related Problem and Solution wording.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/problem-statement-limits-4882ac

---

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.}

[holdex]

Time Submission Status

Member	#	Time	Running Total	Status	Last Update
zolotokrylin			35min	✅ Submitted	Aug 5, 2026, 7:51 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.

[zolotokrylin]

@holdex pr add-time 35m