docs(rules): tell a shipped spec from a plan not yet built

[zolotokrylin]

DEV-180 said to move spec sections into the product docs, but never said why, so the step read as filing work and got skipped on the way to closing a Goal. It now opens with the reason: the product (the app and its end-user docs) is the one source of truth for what exists, and the spec is the one source of truth for what stakeholders still want.

The Problem now names the cost that actually bites. A spec left behind after its behavior ships is indistinguishable from a plan, so readers take shipped work for unbuilt, and the stale text collides with the next spec written for the same feature.

The Solution gains the judgement call that was missing. Product docs are part of the product, carrying what a user cannot work out from the screen alone, so a delivered section graduates only when the UI does not already make it obvious. Everything else is dropped rather than copied, which keeps the docs from bloating into a restatement of the interface.

Two mechanical gaps close with it. The product docs path stays docs/product/ by default and allows a repo to declare its own, and a Goal can no longer be closed while its spec still describes shipped behavior, which is the point where this was being missed.

Both changes are checkable, and the audit and markdown lint pass.

• https://github.com/Curia-Regis/app/issues/305
• https://github.com/Curia-Regis/app/issues/303

Summary by CodeRabbit

• Documentation
  • Clarified how product documentation and specifications serve as separate sources of truth.
  • Added guidance for moving shipped behavior into product documentation while retaining only unfinished work in specifications.
  • Defined documentation locations, handling for expanded scope, and rules for preserving completed specifications.
  • Updated acceptance criteria to ensure documentation reflects shipped behavior without duplicating what the interface makes obvious.

[holdex]

Time Submission Status

Member	#	Time	Running Total	Status	Last Update
zolotokrylin			13min	✅ Submitted	Aug 21, 2026, 5:28 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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: eecf7acb-c181-408b-afc2-a40a9417729b

📥 Commits

Reviewing files that changed from the base of the PR and between de87f58 and ae9195e.

📒 Files selected for processing (1)

• docs/rules/DEV-180.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

DEV-180 now separates product documentation from unbuilt specs. It defines how shipped behavior moves out of specs, how product documentation records non-obvious behavior, and when Goals and completed specs may close or remain.

Changes

Spec and Product Documentation

Layer / File(s)	Summary
Source-of-truth model docs/rules/DEV-180.md	The rule distinguishes the product, including end-user documentation, from the spec. Shipped behavior leaves the spec, while user-required details move to product documentation.
Graduation and closure rules docs/rules/DEV-180.md	The rule defines documentation locations, section graduation, added-scope handling, retained frontmatter, and acceptance criteria for closing Goals.

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

Merge Risk: ⚪ Minimal · up to ae919

This localized documentation update is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

🚥 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 change: distinguishing shipped behavior in product documentation from unbuilt plans in specs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)
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 💡 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 docs/rules-spec-melting

---

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

[zolotokrylin]

@holdex pr add-time 13m