Software Pattern Review

PurposeCopy Anchor Link

Use this checklist at the start of each phase and before merge. Root AGENTS.md, root CLAUDE.md, and scoped frontend/backend instructions define the rules. Read the current feature guide and code. Historical plans are not proof that a workflow exists or that a deprecated implementation is an approved pattern.

Before ImplementationCopy Anchor Link

• Name the domain owner, frontend app, and current comparable implementation.
• Identify source records and supported cross-domain services. Do not duplicate stock, clinical records, billing rules, permissions, or authentication.
• Define the typed request/response contract, permission keys, facility scope, RLS classification, and required audit events.
• Define how each setting changes an actual operation. A stored value alone is not an effective setting.
• Define retries, stale writes, concurrency, errors, and missing-source behavior.
• Record a pattern departure and its reason before implementing it.

Frontend ReviewCopy Anchor Link

• Use shared UI/theme and the owning app's service/adapter/query-key patterns.
• Keep HTTP calls outside components. Keep server state in TanStack Query.
• Use shell identity and effective permissions. Keep flag management in Admin and role/permission management in the shell.
• Enforce the same module-access rule in navigation and direct routes. Preserve case context in workbench handoffs.
• Test facility/profile switches, cache invalidation, and old in-flight responses.
• Check Hooks explicitly: no loop, callback, conditional, or early-return violation.
• Test loading, empty, unavailable, forbidden, conflict, and recoverable errors. Missing APIs cannot silently return mock success or false ready states.
• Run focused tests, the affected build, and canonical frontend CI. Inspect warnings and type errors as well as the process exit code.
• Check user-facing behavior in the browser, including narrow viewports and keyboard access. Use real HTTP mode for API integration acceptance.

Backend ReviewCopy Anchor Link

• Add application code in backend/domains/. Do not depend on deprecated modules.
• Use the owning domain's policies, services, blueprints, and structured errors.
• Test allowed and denied actors, facility scope, and tenant isolation under the non-bypass RLS role. Frontend gates cannot satisfy these checks.
• Update permission defaults, snapshots, access/key-behavior tables, and the policy matrix where the permission contract changes.
• Test atomic writes, stable lock order, stale versions, retries, and races.
• Verify audit evidence and private document access. Do not expose PHI or secrets in logs, exports, review artifacts, or error messages.
• Use forward migrations. Verify migration execution and SQL-schema loading, constraints, indexes, grants, RLS, deployment safety, and recovery.
• Keep structure.sql changes limited to the migration. No migration means no schema diff. Never reset a shared database as a verification shortcut.
• Run focused Minitest and changed-file RuboCop, then canonical backend CI.

Evidence And CompletionCopy Anchor Link

• Record tested head/base commits, commands, results, and review findings.
• Resolve findings and rerun affected checks. If an external review is disabled or unavailable, record that limit; do not report that it passed.
• Update the API, developer, product, QA, and backlog pages that changed.
• Add manual QA checkboxes to the issue or PR at the end of each phase.
• Report implementation, API integration, deployment, manual QA, and pilot approvals separately. Keep the tracking issue open for QA.
• State every approved CI exception explicitly. Never raise a baseline to hide it.

What CI Does Not ProveCopy Anchor Link

These checks combine automated gates and manual review. They are not all lint rules. Backend RuboCop checks changed files. Frontend lint counts errors, not warnings; the React Hooks rule currently warns. TypeScript uses an existing-error baseline. A lower aggregate error count can still hide a new error in changed code, so review the actual diagnostics. Inspect which packages have lint/test tasks before claiming workspace coverage. A successful build does not prove clinical or pilot acceptance.

Use frontend CI and backend CI for canonical commands. Read committed baselines and current output rather than copying a previous run's counts. Confirm GitHub check coverage for the target branch; local evidence is required when the workflow does not run there.

For Hospital, use the developer guide, workflow audit, and release acceptance record.