Repository navigation
docs: backend half of next quarter's AI-context gap backlog (M4, #37129) - #37697
Merged
Merged
Conversation
Backend half of the M4 (#37129) deliverable for the Backend AI-Context Rock (epic #37124): identifies 5 undocumented/under-documented areas (Content Lifecycle, Caching Architecture, Workflow Engine, Upgrade Tasks, docs/integration/ ownership) with rough S/M/L sizing, grounded in real codebase research. This is a draft, not a finished deliverable: it still needs to be merged with Team Scout's testing/tooling half into one document and reviewed with the team before being confirmed as next quarter's Rock. Opening as a draft PR so Team Scout can add their half in the same place rather than a separate doc. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
|
Claude finished @fabrizzio-dotCMS's task in 1m 59s —— View job Review:
|
| Claim | Doc | Actual |
|---|---|---|
ContentletAPI.java |
2,672 lines | 2,672 ✓ |
checkin(...) overloads |
10 | 10 ✓ |
CacheLocator.java |
595 lines | 595 ✓ |
WorkflowAPI.java |
1,261 lines | 1,261 ✓ |
runonce task classes |
246 | 246 ✓ |
Registered in TaskLocatorUtil |
245 | 245 import lines ✓ |
FixTask classes |
18 | 18 ✓ |
CacheProvider impls |
5 (caffine, guava, redis, timedcache, h22) | all 5 present ✓ |
com.dotcms.cache package |
10 classes | 10 (main src) ✓ |
tomcat-redis-session-manager:2.0 in bom/application/pom.xml |
real dep | present (line 1622) ✓ |
API_CONTRACTS.md |
726 lines, ref'd from SECURITY_PRINCIPLES.md:80 |
726 ✓, ref at :80 ✓ |
HealthStateManager has getLivenessHealth() not getLivenessResponse() |
correct | getLivenessHealth() at :186, no getLivenessResponse ✓ |
dot-cicd-diagnose/ISSUE_TEMPLATE.md:90 fabrication (test -Dtest=ContentTypeAPIImplTest#testCreateContentType) |
fabricated | command present at :90 using test -Dtest=; testCreateContentType not found in integration tests ✓ |
The item-4 argument is the strongest and I can confirm its core factual basis: a runonce task not added to TaskLocatorUtil.getStartupRunOnceTaskClasses() compiles and silently never runs — 246 task files vs 245 registered imports is exactly the asymmetry the doc describes. The promotion-to-Critical-Rule recommendation is well-grounded and mirrors the existing MainSuite rule in CLAUDE.md.
Minor / non-blocking (🟡 informational)
docs/BACKEND_GAP_BACKLOG.md:20—ESContentletAPIImplis stated as 10,943 lines;wc -lreports 10,942 (off by one, almost certainly a trailing-newline artifact). Immaterial, but worth a glance given the doc's own standard.docs/BACKEND_GAP_BACKLOG.md:71— "36 real actionlet classes." I count ~41 classesextends WorkFlowActionletunder the workflow package. The doc undercounts rather than inflates, and the phrasing is a rough extensibility estimate, so this isn't a fabrication — but the number is low if someone treats it as exact.docs/BACKEND_GAP_BACKLOG.md:40— "59 distinct cache regions" inCacheLocatorI could not pin to an exact figure by a simple grep (region accessors ≈ 55); it depends on how regions are counted. Not disputing it, just flagging it as the one count I couldn't mechanically confirm.
None of these block merge. Everything that would undermine the backlog's credibility — class existence, method names, dependency presence, the two silent-registration asymmetries, the catalogued fabrications — checks out. The two "candidate for promotion" calls (item 4 upgrade tasks, item 8 content-accuracy check) are factually supported.
No code changes made — this was a review request on a documentation PR.
· docs-37129-backend-gap-backlog
6 of 8 tasks
6 of 8 tasks
Items 6-10, into Jose's existing file rather than a second document, per his
request. Same format as items 1-5: heading with S/M/L size, then what is missing
and why it matters, backed by measurement rather than impression.
6. .claude/skills/ — 14,052 lines across 23 skills, the largest AI-context
surface in the repo, assigned to no team and read by no milestone. The split
gives Scout .claude/commands/ (629 lines), which are wrappers: create-issue.md
is 5 lines pointing at a 630-line skill. Auditing the commands audited the
pointers. A fabrication turned up on the first spot-check — dot-cicd-diagnose
gives -Dtest= for a class that needs -Dit.test=, and names a method that does
not exist.
7. 86 integration test classes that exist and never run in CI (632 registered
against 693 concrete), accumulated since January 2024. Not an active leak —
0 of the last 33 went unregistered — so this is triage, not mechanism.
8. Nothing checks whether a doc's claims are true. Nine surfaces found with
fabricated content this Rock, every one by reading. Includes the sharper
variant CICD_PIPELINE.md showed, where the prose was accurate and only the
copyable YAML was invented, and the fact that the failure reproduced inside a
PR whose purpose was removing fabrications.
9. No upkeep process for .cursor/rules/ and .claude/commands/. The fixes merged;
the reason they drifted did not.
10. The split omitted 10 files, confirmed with Jose. Second occurrence after
docs/integration/ — a process finding, and the argument for the index and
reachability check in #37578 rather than a better manual split.
Title and intro updated to cover both halves; Next Steps records the merge as
done and flags items 4 and 8 as promotion candidates rather than plain entries.
Refs #37580, #37129
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Found after the first draft (#37715). It adds a second variant worth designing against, and a naive "does this symbol exist" check would miss it: e2e-rules.mdc was not invented from nothing but duplicated from AGENTS.md and then drifted. Every symbol in it resolved; the guidance was still wrong — always data-testid, never CSS, against a source of truth that puts getByRole first and permits CSS in the Dojo iframe where data-testid does not exist. And the Cursor rule auto-loads while the doc has to be opened deliberately, so the stale copy won by default. Item 8's surface count goes from four files under .cursor/rules/ to five. Item 9 gains it as the clearest case of the missing upkeep process, and now notes that the reachability check from #37578 covers docs/ but not these two directories. Refs #37580, #37579 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Review caught the backlog asserting a state the tree does not have: items 8 and 9 said e2e-rules.mdc "was folded into a 50-line pointer in #37715", past tense, while #37715 is still open and this branch is cut from Jose's, so the file here is still 223 lines with the src/config/ block that does not exist. That is precisely the failure class items 8 and 9 describe — a claim that reads as verified and resolves against nothing — reproduced inside the document arguing against it. Third time this pattern has appeared in my own work on this Rock, after the API_TESTING overlap asserted from a filename and the invented getLivenessResponse() in #37666. Both places now mark #37715 as open, and item 9 keeps the finding in present tense: until it merges, the contradiction is still what Cursor loads on every spec edit. The merged fixes it lists alongside (#37590, #37629) were verified against the tree and are correctly past tense. Refs #37580, #37579 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Same failure class as the last fix, found by checking rather than by review this time. Four places described the reachability check and the rebuilt index as existing: "the reachability check (#37578) catches unreachable files", "the reachability check added in #37578 covers docs/", "docs/README.md rebuilt as a complete index of all 54 files (#37578)", and "the automated reachability check added in #37578, which runs on every PR touching docs/". #37578 is the issue. Its PR is #37709, which is approved and not merged, so none of that is on main. A backlog arguing that AI-context claims must resolve against real source cannot itself assert a tree state that does not exist. All four now name #37709 and its actual status, and item 10 keeps the point in present tense: until it lands, nothing prevents the next omission. That is the more useful thing for the entry to say. Also updated what has landed since drafting: #37664 and #37721 merged, so docs/cli/, docs/claude/ and docs/test-cases/ are resolved, leaving only the loose docs/core/ file needing an owner. Every figure in items 6-7 re-verified against main today: 14,052 skill lines, 23 SKILL.md, 629 lines across .claude/commands/, 5 lines for create-issue.md against 630 for the skill it wraps, 632 registered / 693 concrete / 86 never run, and the dot-cicd-diagnose fabrication still present at ISSUE_TEMPLATE.md:90. Refs #37580 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
6 of 7 tasks
2 of 3 tasks
fabrizzio-dotCMS
approved these changes
Oct 6, 2026
jcastro-dotcms
marked this pull request as ready for review
October 7, 2026 14:19
erickgonzalez
approved these changes
Oct 7, 2026
erickgonzalez
left a comment
erickgonzalez
left a comment
Member
There was a problem hiding this comment.
Great summary of what is missing, we can/should do some of these as a Rock for Q4.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Backend half (Team Falcon) of next quarter's AI-context documentation gap backlog, drafted as part of the Backend AI-Context Rock (epic #37124, milestone M4 / #37129).
Identifies 5 areas where AI-context docs are missing or inadequate, each with a problem statement grounded in real codebase research and a rough S/M/L documentation-effort estimate:
docs/integration/Ownership — Size: S (a linking/ownership/audit gap, not a missing-doc gap — the doc already exists and looks solid)Why draft
This is not a finished deliverable. Per its own "Next Steps" section, it still needs to:
Opening as a draft now so @fabrizzio-dotCMS (Team Scout) can add their half here, rather than in a separate doc — we'll mark it ready for review once both halves are combined.
Test plan
CLAUDE.md(intentional — this is a transitional backlog doc, not subsystem documentation)