feat(specifiers): add guided diagnosis builder

[BigSimmo]

Summary

• replace the long Specifiers wording form with a focused four-stage guided builder
• add editable progress, a persistent working diagnosis, review/copy/reset actions, and mutually exclusive severity/remission selection
• remove builder breadcrumbs, tighten copy, and preserve existing clinical compatibility and wording rules
• expand responsive, accessibility, clipboard, deep-link, reduced-motion, and forced-colors browser coverage

Verification

• npm run verify:pr-local
  • Partial: runtime, installed-lock parity, changed-file formatting, docs/ledger guards, lint, and typecheck passed.
  • The full unit phase stopped at 18 failures in untouched bundle-budget, Codex Cloud/Bash fixture, and Windows PR-hook tests. One in-scope contextual-back contract finding was corrected afterward; its exact rerun was coordinator-blocked.
• npm run verify:ui
  • Not run: the complete shared Chromium gate was not warranted for a page-local component change.
  • Focused proof: npm run test:e2e -- tests/ui-specifiers.spec.ts --project=chromium passed 9/9 before the final main sync, including 320-1920px layouts, axe checks, focus, clipboard, deep links, reduced motion, and forced colors.
  • The same complete file was started after merging current main but timed out in the buffered build stage after 15 minutes without a reported browser failure; this is not claimed as passed.
• npm run verify:release
  • Not run: release confidence was not requested.
• npm run format: passed on the final merged head; the exact-commit pre-push format guard also passed.
• npm run check:design-system-contract: passed.
• npm run check:production-readiness: environment-gated in the isolated worktree because Supabase and OpenAI credentials are absent; no provider call was made.

RAG impact: no retrieval, ranking, synthesis, or source-rendering behavior change.

Risk and rollout

• Risk: localized Specifiers builder interaction and presentation change; underlying catalogue, applicability, and generated wording contracts are unchanged.
• Rollback: revert the feature commit and its two main-sync merge commits.
• Provider or production effects: None.

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy)
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked; no clinical decision rule or dataset changed

Notes

• Physical iPhone Safari and installed-PWA acceptance were not run.
• The original dirty checkout was not modified; implementation and publication used an isolated worktree.

Summary by CodeRabbit

• New Features

  • Reworked the specifier builder into a guided, step-by-step workflow with progress tracking.
  • Added step navigation, review and editing options, reset controls, and focus management.
  • Added completed-wording review with copy-to-clipboard feedback.
  • Added mutually exclusive severity and remission selections.

• Accessibility

  • Improved keyboard focus, screen reader messaging, reduced-motion support, forced-colors styling, and mobile layouts.

• Bug Fixes

  • Improved navigation and deep-link behavior across builder steps.

[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:20 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: 6f9e1cb6-06e4-49ef-a927-c36f447b12ff

📥 Commits

Reviewing files that changed from the base of the PR and between a01e16b and 7f1d8b0.

📒 Files selected for processing (2)

• docs/design-system/adoption-manifest.json
• tests/ui-specifiers.spec.ts

📝 Walkthrough

Walkthrough

The specifier builder now uses a guided, multi-step workflow with progress tracking, review and edit controls, clipboard copying, reset behavior, focus management, centralized copy, expanded UI tests, and manifest registration.

Changes

Specifier builder workflow

Layer / File(s)	Summary
Builder copy and workflow contracts src/lib/ui-copy.ts, src/components/specifiers/specifier-builder-page.tsx	Adds centralized builder copy and defines the metadata and state used by the staged workflow.
Staged builder interaction flow src/components/specifiers/specifier-builder-page.tsx	Adds step navigation, exclusive severity and remission selection, review editing, reset behavior, clipboard handling, status messaging, and focus management.
Workflow validation and registration tests/ui-specifiers.spec.ts, docs/design-system/adoption-manifest.json	Updates UI coverage for navigation, accessibility, responsive layouts, deep links, copying, editing, and reset flows. Registers the test file in the manifest.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
participant User
participant SpecifierBuilderPage
participant ClipboardAPI
User->>SpecifierBuilderPage: Select specifiers and navigate steps
SpecifierBuilderPage->>SpecifierBuilderPage: Render working wording and review screen
User->>SpecifierBuilderPage: Edit or copy completed wording
SpecifierBuilderPage->>ClipboardAPI: Write completed wording
ClipboardAPI-->>SpecifierBuilderPage: Return copy result
SpecifierBuilderPage-->>User: Show success or failure status

Loading

Possibly related PRs

• BigSimmo/Database#633: Directly evolves the same specifier builder and its UI tests.
• BigSimmo/Database#660: Directly modifies the builder and related UI tests.
• BigSimmo/Database#672: Modifies the same builder workflow and UI test files.

Suggested reviewers:claude

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description covers the required summary, verification results, risk, rollback, provider effects, governance checks, and notes.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a guided diagnosis builder for specifiers.
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 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/chat-specifier-builder-guide-specifier-builder-guide

---

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

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:e8c07e97c8

ℹ️ 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]

@codex resolve actionable Codex review findings for this pull request and current head using the repository instructions. This is the pull request's single automatic repair pass: do not perform a fresh review, create new standalone findings, or request another review. Work only the existing unresolved Codex threads on the current head. The only repository destination is BigSimmo/Database, and the only branch destination is the pull request head branch codex/chat-specifier-builder-guide-specifier-builder-guide at starting commit e8c07e9; never publish fixes to a detached or synthetic work branch and never create a stacked pull request. Use the authenticated GitHub connector to commit each approved fix to BigSimmo/Database:codex/chat-specifier-builder-guide-specifier-builder-guide, then verify that the pull request head contains the published commit before reporting success. Always fix P0 and P1 findings. For P2 and lower findings, fix only clear, scoped, low-risk issues; otherwise disposition them with a concise reason. For a fixed thread, reply with as the first line and as the second line. For a no-code disposition, use followed by . These result markers authorize the workflow to close that exact thread only after it verifies a fixed commit is the pull request head; a local-only commit is not a fix. If publication or verification fails, do not use either result marker, do not claim success, and leave the thread open with the blocker. If human input or new authorization is required, do the same. Finish only after every actionable thread is fixed or dispositioned and closed, or explicitly left open for a human decision. Do not update the branch from main, address unrelated reviews, broaden scope, or create more than one scoped fix commit. Do not use external APIs, paid services, credentials, dependency changes, or broad refactors unless explicitly authorized. Add targeted tests where behavior changes and run the narrowest relevant validation.

[BigSimmo]

@claude Address every currently unresolved inline review thread on this PR against the current GitHub head. The two open threads are duplicate reports of the same visual bug in src/components/specifiers/specifier-builder-page.tsx: the “Not specified” severity/remission radio marker remains visually selected after another option is chosen. Make the border/inner marker conditional on checked state using the repository’s existing radio pattern, add a focused regression that verifies the visible marker state after selecting another radio, run the narrowest relevant formatting/type/test checks, push the minimal fix to this PR branch, reply with the pushed commit SHA and verification, and resolve both satisfied review threads. Do not merge, close, rebase, force-push, deploy, alter auto-merge, or broaden scope.

[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 · #1881

_{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.

[BigSimmo]

Fixed the duplicate review finding on the current head. The Not specified radio marker is now rendered only when that option is checked, so selecting another severity/remission option no longer leaves a misleading inner dot. Both related review threads have been resolved.

[BigSimmo]

@codex Address both currently unresolved inline review threads on this PR against the current GitHub head. They are duplicate reports of the same Not specified radio visual-state defect in specifier-builder-page.tsx. Make the marker/border visibly selected only when the native radio is checked, add a focused regression for selecting another severity/remission option, run narrow formatting/type/test verification, publish the minimal fix to this exact PR head branch using the authenticated GitHub connector, verify the PR head contains the pushed commit, reply to both threads with the exact pushed SHA, and resolve them. Do not merge, close, rebase, force-push, deploy, alter auto-merge, or create another PR.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit:f352e92a57

ℹ️ 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".

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

src/components/specifiers/specifier-builder-page.tsx (1)

313-328: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Reuse severityNotSpecified for the native checked prop.

Line 314 recomputes the same predicate that line 185 already stores in severityNotSpecified. The native checked state and the painted marker then derive from two separate expressions. The defect fixed in this PR came from exactly that split. One source of truth prevents the split from returning.

♻️ Proposed refactor

 type="radio"
name="severity-remission"
aria-label={specifierBuilderCopy.review.notSpecified}
- checked={!selectedRecords.some((record) => record.family === "severity-remission")}+ checked={severityNotSpecified}
onChange={() => chooseSeverity(null)}
className="peer sr-only"

🤖 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 `@src/components/specifiers/specifier-builder-page.tsx` around lines 313 - 328,
Update the native input’s checked prop in the severity selector to use the
existing severityNotSpecified value instead of recomputing the selectedRecords
predicate. Keep the painted marker and checked state driven by this single
source of truth.

tests/ui-specifiers.spec.ts (1)

319-327: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add coverage for the clipboard failure branch.

The init script installs a writeText that always resolves. The component renders errorCopy.clipboardCopyFailed through role="status" when the copy fails, and that branch stays untested. copyTextToClipboard falls back to document.execCommand, so a rejecting writeText alone does not force the failure state; the fallback must also fail.

Add a second case that installs a rejecting writeText and removes document.execCommand, then assert the failure status text.

🤖 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 `@tests/ui-specifiers.spec.ts` around lines 319 - 327, Add a separate test near
“guides choices into a reviewable and copyable diagnosis” that overrides
navigator.clipboard.writeText to reject and disables document.execCommand,
ensuring copyTextToClipboard cannot fall back successfully. Trigger the copy
action and assert the failure message via role="status", using
errorCopy.clipboardCopyFailed as the expected text.

🤖 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 `@tests/ui-specifiers.spec.ts`:
- Around line 354-359: Reorder the assertions in the copy-wording test so the
sessionStorage clipboard value is polled immediately after clicking the “Copy
wording” button, before checking the transient “Copied” label and status text.
Keep the existing expectations and values unchanged, ensuring the clipboard read
completes before the 2200 ms copyState reset.
---
Nitpick comments:
In `@src/components/specifiers/specifier-builder-page.tsx`:
- Around line 313-328: Update the native input’s checked prop in the severity
selector to use the existing severityNotSpecified value instead of recomputing
the selectedRecords predicate. Keep the painted marker and checked state driven
by this single source of truth.
In `@tests/ui-specifiers.spec.ts`:
- Around line 319-327: Add a separate test near “guides choices into a
reviewable and copyable diagnosis” that overrides navigator.clipboard.writeText
to reject and disables document.execCommand, ensuring copyTextToClipboard cannot
fall back successfully. Trigger the copy action and assert the failure message
via role="status", using errorCopy.clipboardCopyFailed as the expected text.

🪄 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

Run ID: f1de2cd9-5971-4736-ad9b-40bc075e208c

📥 Commits

Reviewing files that changed from the base of the PR and between d30a9de and a01e16b.

📒 Files selected for processing (4)

• docs/design-system/adoption-manifest.json
• src/components/specifiers/specifier-builder-page.tsx
• src/lib/ui-copy.ts
• tests/ui-specifiers.spec.ts

[github-actions]

CI triage

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

• Production UI (3) — 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 #10286 (cancelled).

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

[BigSimmo]

Addressed the review finding on the current head eedbd513051f0daa315f46bb51e0742340397f62: the copy test now reads the sessionStorage value before checking the 2200 ms transient label/status window.

[BigSimmo]

@claude Work only the current unresolved review finding on this PR at head a01e16b7aeba0a28d53b092a6f53f3e09801bbf8. Verify the focused Playwright copy-status test race in tests/ui-specifiers.spec.ts: the transient “Copied” UI resets after about 2200 ms while persistence/clipboard polling currently occurs afterward. If valid, minimally reorder the assertions so durable sessionStorage/clipboard state is proven immediately after the click before asserting the transient status, without weakening behaviour coverage. Run the focused spec plus formatting, push the minimal fix to this PR branch, reply with pushed SHA and verification, and resolve the satisfied thread. The existing exact-head shard-3 CI failure in the unrelated differentials compare journey is not part of this specifier change unless the new head independently reproduces an in-scope failure. Do not merge, close, rebase, force-push, deploy, alter auto-merge, or broaden scope.

[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 · #1881

_{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.