promote(org): comments-explain-why

[anshroboto]

Adds an org Standard covering code comments - the one gap where agents reliably add noise and nothing in the commons said not to.

The only existing entry matching "comment" is review-comments-inline-and-human, which is about PR review comments. Nothing governed comments in source.

The rule

Never write a comment that explains what the code already says. Comment only what a reader cannot recover from the file: discovered external-system behaviour, a workaround with a link and a removal condition, a non-obvious invariant or ordering constraint.

Scope

Write-time only, deliberately:

• It does not ask anyone to strip comments from code they are passing through - that would collide with scoped-diffs.
• It says nothing about comments you did not write.
• It does not push a refactor-instead-of-comment rule; simplest-code-that-works already governs extraction.

The closing line names AI diffs explicitly, since narrating every block is their default and this is where most of the noise comes from.

Notes

• 514 chars, in line with neighbouring org entries and well inside the 4000 budget.
• roboto-mem lint is clean for entries/org/. The memory-ci check will still be red - it runs a bare lint and ~30 pre-existing entries/skills/** files fail as unknown scope / missing frontmatter. That predates this branch.

Summary by CodeRabbit

• Documentation
  • Added guidance encouraging comments that explain non-obvious context, external behavior, workarounds, and constraints rather than repeating what the code already shows.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: b9df96ae-eff3-48b2-941d-ad30782501f3

📥 Commits

Reviewing files that changed from the base of the PR and between c2181aa and a74a1ab.

📒 Files selected for processing (1)

• entries/org/comments-explain-why.md

---

📝 Walkthrough

Walkthrough

Adds a standard markdown entry defining metadata and guidance for writing comments that explain non-obvious rationale rather than restating visible code.

Changes

Comment Guidelines

Layer / File(s)	Summary
Explain-why comment guideline entries/org/comments-explain-why.md	Adds a standard entry authored by anshroboto that recommends comments about external behavior, workarounds, removal conditions, and non-obvious invariants.

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

Suggested reviewers: voidhrithik

Poem

A rabbit reads the comment trail,
Where hidden reasons softly sail.
No echoed code, just why it’s so,
With links for paths the hare should know.
Hop by hop, the docs now glow.

🚥 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 reflects the new organization-level standard about comments explaining why rather than restating code.
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 entry/comments-explain-why

Warning

Review ran into problems

🔥 Problems

Errors were encountered while retrieving linked issues.

Errors (1)

• LINEAR integration encountered authorization issues. Please disconnect and reconnect the integration in the CodeRabbit UI.

---

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