Backend AI-Context Rock

[jcastro-dotcms]

Description

Our backend AI context is inconsistent and partially unreachable, so AI-generated code repeats the same mistakes and burns code-review cycles on known issues. Concrete example: new integration tests are generated but never registered in a MainSuite — the rule exists in docs/testing/INTEGRATION_TESTS.md, but it's absent from root CLAUDE.md's Critical Rules and a slash command even contradicts it. AI-assisted code review is similarly inconsistent because its input context is poor: 11 backend docs are orphaned (unlinked from any index, so on-demand loading never reaches them), and live contradictions exist (e.g., CLAUDE.md says Java 25 while JAVA_STANDARDS.md still says Java 11/21).

Scope note: This quarter we fix and consolidate what exists. Writing new subsystem context (content lifecycle, upgrade tasks, caching, workflow, etc.) is explicitly deferred — this Rock produces the documented backlog so next quarter starts execution-ready.

Ownership split

Slice	Owner	Team
docs/backend/, docs/infrastructure/, a 4-file docs/core/ slice, root CLAUDE.md backend sections	Jose Castro	Falcon
docs/testing/, a 5-file docs/core/ slice, .cursor/rules/, .claude/commands/	Fabrizzio Araya	Scout

Fabrizzio's milestones are tracked in his own sub-issues — not created as part of this epic.

Milestone schedule

#	Milestone	Date
M0	Audit & ownership	Aug 20
M1	Fix contradictions	Merge Aug 25 · Gate closes Sep 8
M2	Link orphaned docs	Sep 7
M3	Remove duplication	Merge Sep 21 · Gate closes Oct 5
M4	Publish gap backlog	Draft Oct 5 · Reviewed Oct 8
—	Fixed Rock deadline	Oct 12

⚠️ Deadline risk: at the corrected Aug 18 start, the natural sign-off lands Oct 19 — 7 days past the fixed Oct 12 deadline. Needs a decision before M0 starts: compress roughly a week out of the schedule, or renegotiate the date with stakeholders.

Jose's sub-issues (Falcon)

• M0 — Backend context audit #37125 — M0 — Backend context audit (complete)
• M1 — Fix backend contradictions #37126 — M1 — Fix backend contradictions
• M2 — Link orphaned backend docs #37127 — M2 — Link orphaned backend docs
• M3 — Consolidate backend duplicates #37128 — M3 — Consolidate backend duplicates
• M4 — Backend gap backlog #37129 — M4 — Backend gap backlog

Desired Outcome

This Rock lands when all three Definition-of-Done conditions are true (binary — all three must hold):

1. All consolidation fixes (M1–M3) merged to main.
2. Quality gate passed — each merged context change monitored by its responsible dev against real daily PRs / AI-review output for roughly 1–2 weeks, and the targeted failure mode confirmed stopped recurring (not just "no one touched it").
3. Gap backlog published and reviewed with the team — ready to become next quarter's Rock.

Initial failure-mode watch list (finalized in M0):

• Integration tests created without MainSuite / Junit5Suite registration
• Wrong Java-version idioms suggested by AI
• AI guidance citing docs that contradict each other or don't exist
• AI review missing dotCMS-specific checks because the relevant doc was unreachable

Target Personas

• Developer teams
• Content teams
• DevOps teams
• System administrators (dotCMS)

Links

• Milestone roadmap (Gantt chart)