docs: reviewed and updated Clinical RAG Improvement Programme guide

[BigSimmo]

Summary

• Adds docs/rag-improvement/README.md: a repository-grounded review and updated implementation programme for improving the clinical RAG.
• Corrects the original plan where it conflicted with current evidence or duplicated existing systems:
  • starts Track A1 with structured generation-quality/fallback attribution and provider-safe telemetry, not a presumed route-budget increase;
  • selects any genuinely length-heavy class through initial chooseAnswerRoute routing before its deadline is created;
  • refines the existing buildAnswerFollowUpSuggestions / buildAnswerFollowUpQuery surface rather than adding a duplicate module, response field or render block;
  • preserves the existing fixture command and adds a distinct planned adversarial-fixture contract;
  • incorporates the refuted-approaches ledger and current intent-classification architecture.
• Sequences answer-quality work first: diagnosis, intent-conditioned related-information composition, moderate evidence-supported answer-length expansion, then improvements to the existing follow-up suggestions.
• Retains the evaluation and safety programme for adversarial fixtures, telemetry assessment, Docling lab/shadow evaluation, optional Ragas calibration, a constrained reranker benchmark and deferred DSPy work.
• Adds the documentation catalogue entry and only the forward-reference allowlists still required for genuinely planned files and commands. The obsolete duplicate follow-up-module allowlist was removed.

RAG impact: no retrieval behaviour change — documentation and documentation-validation changes only; no production RAG, ranking, generation or provider behaviour is modified.

Verification

• Current head 460401a31c7be0d0a1f962bca92b60d39268bdc3: CI passed.
• SAST passed.
• Secret Scan passed.
• Exact repository-pinned Prettier output confirmed for docs/rag-improvement/README.md.
• Documentation links, scripts, inventory and index checks passed in hosted CI.
• Existing RAG fixture/evaluation checks were not weakened.
• UI verification not run because this PR changes no UI, routing or browser behaviour.
• Provider-backed evaluation not run because this PR changes no runtime retrieval or generation behaviour.

Risk and rollback

• Risk is limited to documentation accuracy and forward-reference validation. No runtime code, database object, environment value, prompt, model route or provider call is changed.
• Rollback is a normal revert of this PR.
• Future Track A behaviour changes remain separate PRs with their own RAG impact: statement, governance review and live canary evidence where required.

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 31 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ee090340-b1cc-416c-9668-cd213f1b8bca

📥 Commits

Reviewing files that changed from the base of the PR and between a5d11cd and 69d90a9.

📒 Files selected for processing (2)

• docs/rag-improvement/README.md
• scripts/check-docs-links.mjs

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 62c1b6ea-8427-4c05-afe7-b1399dd9bb5a

📥 Commits

Reviewing files that changed from the base of the PR and between 67db5a1 and a5d11cd.

📒 Files selected for processing (5)

• docs/README.md
• docs/branch-review-records/c31311559848676575ed299d92b17501eef76d85f7b516d5d1ec95279fca7162.record.md
• docs/rag-improvement/README.md
• scripts/check-docs-links.mjs
• scripts/check-docs-script-refs.mjs

---

📝 Walkthrough

Walkthrough

This change adds a maintained RAG improvement guide, documents evaluation and release controls, indexes the guide, records verification results, and updates documentation checker allowlists for planned RAG paths and commands.

Changes

RAG documentation and governance

Layer / File(s)	Summary
Guide scope and current-state baseline docs/rag-improvement/README.md	Defines the guide scope, protected surfaces, corrected review conclusions, and existing RAG pipeline behavior.
Answer-quality improvement track docs/rag-improvement/README.md	Defines Track A work for route budgets, answer composition, answer length, and deterministic follow-up suggestions.
Evaluation infrastructure and release controls docs/rag-improvement/README.md, docs/branch-review-records/...record.md	Defines adversarial evaluation, extraction and ranking experiments, release gates, sequencing, verification, rollback, and the completed branch review record.
Documentation index and checker wiring docs/README.md, scripts/check-docs-links.mjs, scripts/check-docs-script-refs.mjs	Adds the guide to the maintained-doc index and allowlists planned RAG paths and command references.

Estimated code review effort: 2 (Simple) | ~10 minutes

Mergeability Score: ⚪ Minimal · up to a5d11

This change updates documentation and documentation-consistency allowlists without changing runtime or retrieval behavior. The listed checks pass, and no actionable merge-blocking risk remains beyond normal review.

Possibly related PRs

• BigSimmo/Database#443: Concerns related RAG improvement documentation and governance.
• BigSimmo/Database#446: Covers related RAG implementation and evaluation changes.
• BigSimmo/Database#616: Introduced the documentation script-reference allowlist updated here.

Suggested labels: codex

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly identifies the reviewed and updated Clinical RAG Improvement Programme guide, which is the main change.
Description check	✅ Passed	The description covers the summary, verification evidence, risk, rollback, and explains why UI and provider-backed checks were not run.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/rag-plan-review-guide-vhrls9

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 11d9cdd12b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[BigSimmo]

@claude Please address all three unresolved review findings on exact head a5d11cdb801eeaab436862417d5ff0e3167e7367, commit and push one focused docs-only fix to this PR branch, and do not merge, rebase, force-push, close the PR, alter auto-merge, or edit unrelated files.

In docs/rag-improvement/README.md:

1. Correct the fix(ci): bump checkout/setup-node/cache actions to v5 #231 diagnosis. The canonical issue already refutes increasing 35–40s route/provider timeouts: generation completed within budget but failed generation quality, and the stop condition says not to increase timeouts. A1 must start with the recorded structured generation-quality diagnosis plus provider-safe, allow-listed instrumentation; remove budget-headroom/timeout increase as the prerequisite.
2. Correct A4’s current-state claim. src/lib/answer-follow-up.ts already implements buildAnswerFollowUpSuggestions, and ClinicalDashboard.tsx already computes and renders wired mobile/desktop chips. Re-scope A4 to the actual missing evidence-gating/composition improvements on the existing surface. Do not prescribe a duplicate module, RagAnswer field, or render block.
3. For length-heavy classes, route them before the fast attempt through chooseAnswerRoute/initial routing. Do not point this mitigation at shouldRetryWithStrongAfterFast, which runs only after fast generation under the already-created fast deadline.
4. Keep Track A sequencing and file/gate guidance internally consistent after these corrections. Run the smallest docs/format/link checks and report exact outcomes.

[github-actions]

Hi @BigSimmo — thanks for the @claude mention.

Open this in Claude Code on the web to continue here: https://claude.ai/code

Context: BigSimmo/Database · #1895

_{Automated backlink from the Claude backlink workflow. Claude Code can pick up the mention and push a scoped fix to the branch.}

[claude]

Claude encountered an error after 2s —— View job

---

I'll analyze this and get back to you.

[github-actions]

CI triage

CI failed on this PR. Automated classification of the 2 failed job(s):

• Static PR checks — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.
• PR required — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.

Compared with main CI run #10317 (success).

Classification is evidence routing, not permission to ignore a failure. Exact quarantined Playwright identities remain governed by the flake ledger.

[BigSimmo]

Fixed the exact current-head static CI failure by formatting docs/rag-improvement/README.md with the repository formatter. No content or scope changes were made; auto-merge remains enabled and fresh CI is pending.