docs: add code comment brevity rule to global agent context

[UnstoppableMango]

Comments should document behavior the code does not make obvious.
Longer reasoning belongs in markdown under docs/.

Co-Authored-By: Claude Opus 5 noreply@anthropic.com

Summary by CodeRabbit

• Documentation
  • Added guidance for writing concise, behavior-focused code comments.
  • Clarified that historical context and decision background should be documented separately.
  • Encouraged refactoring code to improve self-explanatory behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 70e28027-ede2-44ed-ac01-4b9ad70e141b

📥 Commits

Reviewing files that changed from the base of the PR and between e6117bc and 29847c3.

📒 Files selected for processing (1)

• modules/ai/global-context.md

Included review availability: Your plan provides up to 10 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The AI global context now guides concise, behavior-focused comments. It recommends refactoring for clarity and placing historical reasoning in documentation.

Changes

Comment Guidance

Layer / File(s)	Summary
Comment-writing rules modules/ai/global-context.md	Adds guidance to keep comments brief, document non-obvious behavior, prefer clear refactoring, and place historical context in docs/.

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

Merge Risk: ⚪ Minimal · up to 29847

This updates global guidance for concise, behavior-focused code comments without changing runtime behavior or public interfaces. No merge-readiness 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 and concisely describes the main change: adding a code-comment brevity rule to the global agent context.
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…
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/comment-brevity

---

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

[Copilot]

🟢 Approval recommended

The change is low-risk documentation-only guidance with no functional impact on configurations or modules.

Pull request overview

Updates the global agent context guidance to encourage concise, behavior-focused code comments, steering longer rationale toward markdown documentation.

Changes:

• Added a “code comment brevity” rule emphasizing comments that clarify non-obvious behavior.
• Encouraged refactoring over explanatory comments when code can be made self-explanatory.
• Suggested placing decision/history context in markdown documentation rather than inline comments.

File summaries

File	Description
modules/ai/global-context.md	Adds guidance for brief, high-signal code comments and directs longer rationale to markdown docs.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.