docs: avoid needless compatibility layers

[jan-kubica]

Adds general guidance to require a concrete support boundary before introducing compatibility machinery.

CC on behalf of jan-kubica

Summary by CodeRabbit

• Documentation
  • Added guidance to assess concrete backward-compatibility requirements before introducing compatibility measures.
  • Clarified that clean migrations or cutovers are preferred when compatibility is not required.
  • Added requirements to document compatibility boundaries and removal conditions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 93f3109e-3794-444e-bec5-1037d73bc162

📥 Commits

Reviewing files that changed from the base of the PR and between 473b2ce and c2b2266.

📒 Files selected for processing (1)

• modules/engineering.md

📜 Recent review details

🔇 Additional comments (1)

modules/engineering.md (1)

12-16: LGTM!

---

📝 Walkthrough

Walkthrough

The engineering guidance now requires concrete compatibility requirements before using compatibility machinery. It favours clean migration or cutover when no such requirement exists. It also requires compatibility boundaries and removal conditions.

Changes

Compatibility guidance

Layer / File(s)	Summary
Compatibility rules modules/engineering.md	The guidance discourages aliases, dual reads or writes, and staged compatibility paths unless specific compatibility requirements exist. It requires documentation of compatibility boundaries and removal conditions.

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

Possibly related PRs

• stella/ai-shared#38: Both changes update engineering guidance for justified compatibility decisions and explicit migration details.

🚥 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 summarises the documentation change about avoiding unnecessary compatibility layers.
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/no-needless-compatibility

---

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