docs: surface conflicting patterns instead of averaging them

[jan-kubica]

Adds a Meta Preferences bullet for the case where two existing patterns in a
codebase contradict each other. Nothing in the module covered it, so the
implicit default was to imitate both and produce a third hybrid pattern.

The rule:

• Adopt one pattern, never blend.
• Precedence: documented convention and enforced guards, then most recent
  well-tested code, then most widespread. Recency alone is a weak tiebreaker;
  the last thing to land can simply be wrong.
• A convention that disagrees with a guard is itself the finding, reported
  rather than silently resolved.
• Report the winner, the losing call sites, and a concrete unification
  proposal. The call-site enumeration is already done by the time a winner is
  picked; discarding it is the waste.
• Unifying is a scope decision left to the user. Where they defer, land the
  guard so the losing pattern can only shrink.

The last point keeps this from colliding with the existing "fix pre-existing
bugs" bullet: a losing-but-working pattern is not a defect, and converting its
call sites unasked turns a small diff into an unrequested review burden.

Placed after the silent-drift bullet, which covers the adjacent topic of
structures diverging from each other.

Consuming repos pick this up on their next submodule bump plus sync-ai.

CC on behalf of jan-kubica

Summary by CodeRabbit

• Documentation
  • Added guidance for resolving conflicting implementation patterns.
  • Clarified prioritisation of documented conventions, enforced safeguards, recently tested code, and widespread usage.
  • Added requirements to report decisions, identify superseded patterns, and propose a route to standardisation.

[coderabbitai]

📝 Walkthrough

Walkthrough

Added engineering guidance for resolving conflicting patterns. The guidance defines precedence, requires reporting of chosen and losing patterns, and specifies codemods, enforcement mechanisms, or interim guards for deferred unification.

Changes

Engineering guidance

Layer / File(s)	Summary
Conflict-resolution guidance modules/engineering.md	Defines precedence for documented conventions, enforced guards, recent well-tested code, and widespread usage. Requires reports of conflicting call sites and proposed unification mechanisms. Requires an interim guard when unification is deferred.

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

🚥 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: reporting conflicting patterns instead of combining them.
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/surface-conflicts

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@modules/engineering.md`:
- Line 40: Update the sentence containing “they defer, land the guard” by
inserting a comma before “so,” yielding “land the guard, so the losing pattern
can only shrink.”

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d7a21a9-587f-49b0-8479-b8af01b27617

📥 Commits

Reviewing files that changed from the base of the PR and between ff844be and 12a7fe5.

📒 Files selected for processing (1)

• modules/engineering.md

📜 Review details

🧰 Additional context used

🪛 LanguageTool

modules/engineering.md

[uncategorized] ~40-~40: Use a comma before ‘so’ if it connects two independent clauses (unless they are closely connected and short).
Context: ... moment; if they defer, land the guard so the losing pattern can only shrink. - A...

(COMMA_COMPOUND_SENTENCE_2)

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add a comma before so.

Line 40 joins two independent clauses. Write land the guard, so the losing pattern can only shrink to keep the guidance grammatically clear.

Proposed fix

-  they defer, land the guard so the losing pattern can only shrink.
+  they defer, land the guard, so the losing pattern can only shrink.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	they defer, land the guard so the losing pattern can only shrink.
	they defer, land the guard, so the losing pattern can only shrink.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~40-~40: Use a comma before ‘so’ if it connects two independent clauses (unless they are closely connected and short).
Context: ... moment; if they defer, land the guard so the losing pattern can only shrink. - A...

(COMMA_COMPOUND_SENTENCE_2)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@modules/engineering.md` at line 40, Update the sentence containing “they
defer, land the guard” by inserting a comma before “so,” yielding “land the
guard, so the losing pattern can only shrink.”

Source: Linters/SAST tools