Skip to content

Study Management Programme

Decision requested

Approve a phased redesign of the project Studies area, rather than merging any historical Study Management branch or treating PR #2990 as the finished feature.

The approved information architecture uses a Study management navigation group with three stable destinations. Short navigation labels are paired with precise page titles:

  1. Library / Study library — browse and filter study records; launch Bulk Study Update; show the current or latest update and link to its processing history (the history the server retains).
  2. Searches / Systematic searches — create and manage searches; show current or latest Search Import and Bulk PDF state in context (Risk of Bias omitted since 2026-09-02: the feature is disabled and on ice — see acceptance-criteria.md).
  3. Processing / Processing activity — the canonical read-only view of the retained history across permitted long-running operations, with links back to the owning screen.

This preserves the domain distinction between studies and searches while making long-running work consistently discoverable. It does not create a universal backend job type or place unsupported commands behind generic buttons.

MVP boundary

The first genuinely usable release is the smallest end-to-end slice that lets an authorised user:

  • launch a Bulk Study Update from the Library and find the same operation in Processing after navigation or refresh;
  • see exact status, truthful progress, bounded errors, initiator when the server can prove it, and valid created/updated/completed timestamps without year-one defaults;
  • follow consistent links among Library, Searches, Processing, and the owning context;
  • use the experience at 320 CSS pixels, at 200–400% zoom, with keyboard and screen reader; and
  • receive stable state during loading, reconnecting, partial failure, completion, and live updates.

The shortest critical path is: contract truth → Claude Design iteration → shared presentation adapters → Library vertical slice → Searches consistency → Processing destination → final audit.

Cancellation and retry are capability-specific. Bulk PDF retains the commands it already supports. Search Import, Bulk Study Update, and Risk of Bias do not gain cancel/retry UI until a separate backend PR defines safe semantics and permissions for that job family.

Acceptance criteria for the plan gate

  • Historical Study Management issues, PRs, branches, and feature documentation are reconciled.
  • Current-main routes, APIs, projections, stores, job models, permissions, and deployed flags are inventoried.
  • PR #2990 is classified as prototype evidence, with its correctness defects and useful parts recorded.
  • Central and contextual job responsibilities are explicit.
  • Material 3, responsive, high-zoom, accessibility, live-update, and state requirements are contractual rather than deferred polish.
  • Implementation is split into independently reviewable PRs with file ownership, dependencies, focused tests, rollout, rollback, and staging proof.
  • Product approves Library / Searches / Processing and the read-only Processing boundary.
  • Claude Design completes the reviewed interaction and responsive design iteration (approved 2026-09-01; see design-decision.md).
  • Security/product approve the permission matrix before any aggregate job view is exposed (Wave 1B supplies the server-filtered proof; gates Wave 5 exposure, not implementation start).
  • Material 3 PR #2994 lands or publishes its final token/navigation contract on main (merged; its contract is an ancestor of this plan's base).

Recovered history and disposition

Artefact Recovered intent Decision
PR #1865 Unified Study Management page with upload, Bulk Update, and progress Closed prototype; retain user intent and test ideas, not code
PR #2511 Monorepo rebase of the same combined page Closed prototype; superseded
PR #2528 Large admin/project job-progress implementation behind newStudyManagement Do not merge; preserve evidence, split by the waves in this plan, then close as superseded
PR #1875 Tests for the pre-monorepo implementation Preserve behavioural scenarios only; paths and component assumptions are obsolete
Issue #1917 / FEAT-018 Original integration checklist and known last-modified mismatch Replace the stale checklist with this programme; keep the issue as historical tracking until new slices exist
Issue #2562 Production-ready refactor of the admin job progress UI Separate admin-monitor successor; it does not own the project Studies experience
PR #2990 Bulk Study Update history on Systematic Searches Prototype evidence; do not merge in current form; supersede after the Library slice is reviewed
PR #2993 Central Jobs hub plan Reused as the canonical plan-only PR and broadened to this complete programme
PR #2612 Staged Search Import design Retain as a backend evolution dependency; do not absorb into the UI programme
PRs #2858, #2887, #2900 Search-upload metadata and Bulk Update operational recovery Retain and sequence; avoid their owned files
PRs #2976, #2979 Bulk PDF runtime/release and hosting plans Retain as authoritative Bulk PDF dependencies; avoid their owned files
PR #2994 Material 3 tokens and adaptive-navigation contract Read-only design dependency; Study Management retains product/domain ownership
PRs #2992, #3010 About/navigation and Admin responsive work Explicitly out of scope and untouched

Why PR #2990 is not the end state

PR #2990 usefully demonstrates a bounded error disclosure, responsive table-to-card treatment, explicit Bulk Study Update status copy, and focused component tests. Those ideas should be reused after their data contract is corrected.

It diverges from the required programme in material ways:

  • it puts project-wide Bulk Study Update history on Systematic Searches, although the launch action belongs in Library and canonical history belongs in Processing;
  • it covers one job type without resolving entry points, navigation, refresh behaviour, or the relationship between contextual and central monitoring;
  • it can report parsed rows as updated studies even when no study changed;
  • its ordinary-member initiator lookup can display Unknown Investigator because the server projection omits secure related investigators;
  • DateTimeLastModified is not mapped from the domain LastModified property, so the DTO can expose a year-one default and sort incorrectly;
  • it assumes no backend work is required despite those correctness and permission defects; and
  • it does not reconcile Search Import, Risk of Bias, Bulk PDF, mobile/high-zoom behaviour, or the shared Material 3 status contract.

PR #2990 must remain untouched until this plan is reviewed. If the Library slice is approved, that implementation PR should explicitly supersede #2990 and carry forward only verified pieces.

Planning pack

Ownership and coordination

This plan owns Study Management product decisions and future files under a dedicated project/study-management feature boundary plus the explicitly listed contextual screens. Each implementation PR must publish its exact file ledger before editing and must not have a second writer.

PR #2994 has merged, so this plan now consumes its Material 3 contract and may regenerate the feature indexes and MkDocs navigation. PRs #2900 and #2979 still touch CLAUDE.md; the durable agent-context pointer must therefore be added conflict-free after those owners land. This is a sequencing dependency, not permission to modify another task's file.

Remaining product decisions

  1. Use Claude Design to validate the Processing default, filter hierarchy, disclosure model, and contextual summary pattern before implementation. Closed — approved 2026-09-01 (design-decision.md).
  2. Confirm project members may see only operation families already authorised by server projection. Route visibility is decided by explicit PermissionReport capabilities — never by "absence of every family", which is indistinguishable from an authorised project with no jobs yet.
  3. Confirm history retention/pagination remains the current aggregate behaviour for the MVP. Closed — the brief scopes the MVP to the retained ProjectDetails aggregate with a paged historical API as evidence-triggered follow-up.

The Claude Design gate is accepted; decision 2's server-side proof lands with Wave 1B and gates Wave 5 exposure.