@hippo-digital/hippocampus 1.0.0-rc.1

package/docs/custom-agents-usage.md

@@ -0,0 +1,95 @@
+# Custom Agents Usage
+
+Custom agents should be used for focused review loops. The source model remains the shared contract between them.
+
+Task recipes now live in `.github/skills/`. Use role agents for delegation, then follow the linked skill file for the exact read/edit/run flow.
+
+For old prompt lookups, use `.github/skills/COVERAGE-MATRIX.md` to map archived prompt names to the current skill and role-agent entrypoints.
+
+After changing the skill catalog or any `*.skill.md`, run `npx hippocampus skills validate`.
+
+For cross-runtime examples, see `.github/skills/examples/`.
+
+## Suggested Agents
+
+### knowledge-builder
+
+Maintains `hippocampus/source`, links records, adds assumptions and runs validation.
+
+Use for:
+
+- service slice generation
+- user needs and scenarios
+- journeys and blueprint source data
+- traceability audits
+
+### prototype-builder
+
+Builds or adjusts NHS Prototype Kit routes and Nunjucks views.
+
+Use for:
+
+- adding prototype screens
+- rendering new source-model fields
+- improving page states and navigation
+
+### ingestion-curator
+
+Improves script-generated research and project-context drafts before promotion.
+
+Use for:
+
+- end-to-end research round ingestion via `ingest-research-round`
+- end-to-end project-context ingestion via `ingest-project-context`
+- research draft structuring
+- project context draft structuring
+- import draft review
+- mapping reviewed research to existing graph entities
+
+### screenshot-runner
+
+Captures visible review evidence for changed routes.
+
+Use for:
+
+- journey review packs
+- before and after screenshots
+- checking responsive layouts
+- route review packs via `capture-route-review-pack`
+- route review handover notes via `write-route-review-summary`
+
+### accessibility-tester
+
+Reviews pages against basic accessibility expectations.
+
+Use for:
+
+- heading order
+- labels and link text
+- keyboard navigation
+- colour and component usage
+- dated accessibility notes via `record-accessibility-review`
+- route review handover notes via `write-route-review-summary`
+
+### workflow-orchestrator
+
+Coordinates multi-step work across source, prototype, validation and review artefacts.
+
+Use for:
+
+- full service slices via `deliver-service-slice`
+- full research or project-context ingestion handoff
+- release-style delivery summaries via `write-delivery-summary`
+- screenshot and accessibility review handoff via `write-route-review-summary`
+- larger design review packages
+
+## Output Locations
+
+- Source data: `hippocampus/source`
+- Import drafts: `hippocampus/imports/research`, `hippocampus/imports/project`
+- Prototype views: `app/views`
+- Routes: `app/routes.js`
+- Generated screenshots: `artefacts/screenshots`
+- Accessibility notes: `artefacts/accessibility`
+- Delivery notes: `artefacts/delivery-summaries`
+- Generated docs: `artefacts/generated-docs`

package/docs/design-actions-and-decisions.md

@@ -0,0 +1,95 @@
+# Design actions and decisions
+
+How the design process is recorded so that a screen can be traced back to the
+research that shaped it, and to the options that were considered and turned down.
+
+## The process this models
+
+```text
+findings and insights
+  -> design actions agreed with the team   (open: several directions possible)
+  -> options weighed against each action
+  -> one decision accepted
+  -> into production
+```
+
+A **design action** is the open brief. It is not a solution and not a commitment.
+One action can be answered by several options, and several insights can point at
+one action.
+
+A **decision** is one option weighed against an action. All the options sit as
+`proposed` while the team is deciding; then one becomes `accepted` and the rest
+`rejected`. `superseded` is for a later round overturning an earlier call — use it
+rather than editing the original, so the reversal is visible.
+
+This needs no record type the knowledge base did not already have.
+`DecisionSchema` has carried `proposed / accepted / rejected / superseded` all
+along; it was only ever used for five notes about the prototype spike.
+
+## Why the rejected options matter
+
+The accepted option ends up in production, where anyone can see it. The rejected
+ones are the ones that get asked about eighteen months later — "why didn't NCRS
+just do the obvious thing?" — and by then the answer lives in one person's memory
+or in a meeting no one recorded. A rejected decision record with a `consequence`
+answers it.
+
+## The workbook
+
+`hippocampus/templates/ncrs-insight-design-action-tracker.xlsx`, one copy per round.
+Three sheets that reference each other by ID:
+
+| Sheet | One row per | Key columns |
+| --- | --- | --- |
+| Insights | finding | `ID`, `Insight / feedback summary`, `Signal strength`, `Design action IDs` |
+| Design Actions | direction to explore | `ID`, `Action`, `Rationale`, `Status`, `Insight IDs` |
+| Decisions | option weighed | `ID`, `Design action ID`, `Option`, `Status`, `Decision`, `Consequence` |
+
+Status columns are dropdowns bound to the schema's own vocabularies, so a status
+cannot drift into something that will not import.
+
+### Write an action once
+
+If eleven insights share one design action, the action is one row on the Design
+Actions sheet with eleven insight IDs against it. This is the single most important
+rule, and the reason the sheets are split.
+
+The Round 16 tracker had no Design Actions sheet — the action was a free-text column
+on each insight row — so "Whole search re-design and integration of requirements" was
+retyped on every row it applied to, drifting slightly each time. It imported as three
+near-identical design actions that no script could reconcile, because there was no
+way to tell a genuine variant from a retyping.
+
+### Status is status
+
+The Round 16 tracker's `Status` column held priority values, so design action status
+had to be inferred from `Next Action` instead. Priority is a different question and
+belongs in its own column.
+
+## Importing
+
+```bash
+npx hippocampus import design-actions -- --workbook <path> --dry-run
+npx hippocampus import design-actions -- --workbook <path>
+npx hippocampus validate
+```
+
+The importer refuses the workbook rather than importing something broken, and names
+what to fix. It checks that every insight ID exists in the knowledge base, that every
+design action ID a decision points at exists, that statuses are in the permitted set,
+and that no action has two accepted options. It validates the whole knowledge base
+before writing anything, so a bad workbook cannot leave source data broken.
+
+## How this traces
+
+Relationships point from a dependent to what it relies on, because evidence impact
+walks `relationship.to -> relationship.from`:
+
+```text
+decision --resolves-action--> design action --responds-to-insight--> insight --supported-by--> evidence
+```
+
+Asking for the impact of a piece of evidence now returns the insights, the design
+actions and the decisions that rest on it. Before this, `insight --leads-to-action-->
+action` pointed the other way and the walk stopped at the insight — the design work
+was invisible to exactly the question worth asking of it.

package/docs/gp-connect-real-data-to-production.md

@@ -0,0 +1,66 @@
+# GP Connect: Real Data → Production Workflow
+
+This doc connects four repos into one pipeline: pulling real GP Connect/PDS data, rendering and reviewing it in `ncrs-prototype-agentic`, capturing the resulting UI decisions where they belong, and making those decisions available to production builds in `ncrs-ui`. Hippocampus integration is a later, explicitly deferred stage — see Stage 6.
+
+If anything here conflicts with `ncrs-prototype-agentic/ARCHITECTURE.md`, that file wins.
+
+## Repos involved
+
+| Repo | Role in this workflow |
+| --- | --- |
+| `gpconnect-ui-testdata` | Bruno collection for pulling real bundles from GP Connect providers (JWT pre-request script, TLS-MA). Also a scratch space for prototyping a new edge case before it's formalised. |
+| `ncrs-prototype-agentic` | Renders bundles, hosts the canonical synthetic-fixture pipeline, and is where edge-case-driven UI decisions get written down. |
+| `ncrs-ui` | Production React build. Its Copilot skills read `ncrs-prototype-agentic`'s decision records when porting a component. |
+| `nhs-prototype-hippocampus` (this repo) | Structured design knowledge base. Not yet wired to clinical/FHIR content — see Stage 6. |
+
+## Stage 1 — Acquire real bundles
+
+Use the Bruno collection in `gpconnect-ui-testdata/bruno`. It has a working `alg: none` JWT pre-request script and environments for Integration and the local demonstrator.
+
+Blocked on: NHS integration credentials (`sspPrefix`, `providerFhirBase`, `consumerAsid`/`providerAsid`, `consumerOdsCode`, `sdsUserId`, `sdsRoleProfileId`) via your org's assurance process. Client cert for TLS-MA if calling a real provider rather than the local demonstrator.
+
+SystmOne-in-Parallels is a secondary reality check for one specific quirk, not the main data loop — it validates on entry and won't produce most of the interesting edge cases.
+
+## Stage 2 — Bring bundles into ncrs-prototype-agentic
+
+Two landing spots, depending on shape:
+
+- **Single-patient real/reference bundles** → `app/data/gpud-data-*.json`, wired up via `getGpConnectDataFileName()` in `app/lib/gpconnect/core.js`. Fine for one-off "does this real bundle render" checks.
+- **Multi-source, scenario-driven synthetic bundles** → the canonical fixture pipeline: `test-data/clinical-scenarios/*.json` → `scripts/build-clinical-fixtures.mjs` → `test-data/generated/<scenario-id>/`. See `docs/CLINICAL-DATA-FIXTURES.md` (in `ncrs-prototype-agentic`) for the full model (persona / canonical truth / per-source includes-overrides-omits).
+
+**Decision on blood pressure specifically:** the BP generator in `gpconnect-ui-testdata/generate.js` was built before `ncrs-prototype-agentic`'s fixture pipeline was reviewed. `docs/plans/synthetic-fhir-test-suite-builder.md` (in `ncrs-prototype-agentic`) already scoped `Observation` into the canonical builder from the start. Fold the 15 BP scenarios into `test-data/clinical-scenarios/` as `Observation`-based scenario specs (persona/truth/source-matrix shape) rather than maintaining `generate.js` as a second system long-term. Keep `gpconnect-ui-testdata` for the Bruno collection and for prototyping the *next* new edge case idea before it's formalised there.
+
+## Stage 3 — Render, review, check
+
+In `ncrs-prototype-agentic`:
+
+- Follow `docs/GP-CONNECT-UI-CHANGE-CHECKLIST.md` before touching the live GP Connect surfaces.
+- Run `npm run test:clinical-fixtures` for scenario-driven work (build → audit → compare against `expected-clusters.json`).
+- Use `@screenshot-runner` / `@accessibility-tester` per `docs/AGENT-WORKFLOW.md` for the review loop.
+
+## Stage 4 — Capture the decision
+
+Each edge case forces a "what should the UI do here" decision. Write it into `ncrs-prototype-agentic`'s `docs/components/<component>.md` using the existing template (`docs/components/template.md`) — not a new artefact type. The template's **Design intent**, **Parameters**, and **Testing and validation → Regression risks** sections are exactly where FHIR-edge-case behaviour belongs (e.g. `dataAbsentReason` handling, the `Observation.related` escape hatch, qualifiers flattened into `comment`).
+
+This is the load-bearing step: it's the only thing `ncrs-ui`'s skills read in Stage 5.
+
+## Stage 5 — Production skills consume the decision
+
+`ncrs-ui/.github/prompts/port-ncrs-nunjucks-component.prompt.md` currently inspects only the Nunjucks source when porting a component. Extend it (or add a paired skill) to read the matching `ncrs-prototype-agentic/docs/components/<component>.md` first, and to check whether the documented edge cases are represented in the ported component's tests/Storybook states.
+
+Adopt the portable skill format this repo already built and validated — `.skill.md` + YAML front matter (`id`, `purpose`, `owners`, `reads`, `edits`, `runs`, `outputs`, `guardrails`, `acceptance`), checked by `npx hippocampus skills validate`. It's plain Markdown/JSON, works today as a Copilot custom prompt, and is the actual answer to "tool-agnostic" — no need to invent a second format for `ncrs-ui`. See `.github/skills/SKILL-FORMAT.md`.
+
+## Stage 6 — Hippocampus integration (deferred)
+
+`docs/agentic-patterns-to-port.md` (this repo) already flags the clinical FHIR fixture workflow as low-value/defer: it is powerful but NCRS-specific and would pull the knowledge base toward clinical data testing before the service design model is proven. Don't revisit until Stage 4 has produced enough decision records across GP Connect sections (not just BP) to be worth making queryable that way, or a slice specifically needs structured clinical data provenance / source contradiction / fixture generation surfaced through hippocampus.
+
+`ncrs-prototype-agentic/ARCHITECTURE.md` step 7 ("optional evidence-linked handoff") already anticipates a hippocampus link via `hippocampus/prototype-maps/<journey-slug>.json` — that's the hook to extend when this stage is triggered, not a new integration point.
+
+## Cross-references
+
+- `ncrs-prototype-agentic/docs/CLINICAL-DATA-FIXTURES.md` — canonical fixture pipeline
+- `ncrs-prototype-agentic/docs/plans/synthetic-fhir-test-suite-builder.md` — original design scope (includes `Observation`)
+- `ncrs-prototype-agentic/docs/GP-CONNECT-UI-CHANGE-CHECKLIST.md` — before changing live GP Connect UI
+- `ncrs-prototype-agentic/docs/components/template.md` — decision-capture template
+- `.github/skills/SKILL-FORMAT.md` — portable skill contract
+- `docs/agentic-patterns-to-port.md` — deferral rationale for Stage 6

package/docs/hippocampus-for-designers-and-researchers.md

@@ -0,0 +1,261 @@
+# Hippocampus for Designers and Researchers
+
+Hippocampus is a place to keep design knowledge in a structured way.
+
+It helps a team connect research, user needs, scenarios, journeys, prototype screens, decisions and evidence so the work does not become scattered across decks, screenshots and notes.
+
+## What It Is For
+
+Hippocampus helps answer questions like:
+
+- Who is this service for?
+- What do those users need?
+- What evidence supports those needs?
+- Which scenarios are we designing for?
+- Which journeys and screens respond to those scenarios?
+- Why did we make this design decision?
+- What might be affected if a piece of evidence changes?
+
+The aim is traceability. A prototype screen should not just exist as a page. It should connect back to the research, needs and decisions that shaped it.
+
+## The Main Idea
+
+Think of Hippocampus as the project memory.
+
+The source folder contains structured knowledge:
+
+```text
+hippocampus/source/
+```
+
+The viewer turns that knowledge into pages:
+
+```text
+/hippocampus
+```
+
+So the team can browse the work without reading JSON files.
+
+## What Goes Into It
+
+Hippocampus stores different kinds of design knowledge.
+
+**Users**  
+The groups of people involved in or affected by the service.
+
+**Project context**  
+The general service overview: purpose, vision, problem statement, policy context, service channels, constraints, risks, milestones and key facts.
+
+**User needs**  
+Specific needs that should influence the design.
+
+**Scenarios**  
+Realistic situations where a user needs to do something.
+
+**Journeys**  
+Step-by-step flows through a scenario.
+
+**Prototype screens**  
+Screens built in the NHS Prototype Kit and linked back to needs.
+
+**Evidence**  
+Research, documents, scenario maps or other sources that support the work.
+
+**Decisions**  
+Design or product decisions, including the reason and consequence.
+
+**Research rounds, participants, insights and actions**  
+Research material that can be linked into the rest of the knowledge base.
+
+## How The Graph Works
+
+The graph is a map of links between things.
+
+For example:
+
+```text
+user -> has need -> supported by evidence
+scenario -> tests need
+scenario -> drives journey
+journey -> renders screen
+screen -> addresses need
+decision -> records why something changed
+```
+
+This means the team can move through the work from different directions.
+
+You can start with a user and see:
+
+```text
+their scenarios
+their needs
+the evidence behind those needs
+the journeys and screens already generated
+the decisions connected to those screens
+```
+
+Or you can start with evidence and see:
+
+```text
+which needs, journeys, screens or decisions depend on it
+```
+
+That is useful when research changes or when someone asks, "Why is this screen designed like this?"
+
+## User Graph Pages
+
+Each user can have a graph page.
+
+Example:
+
+```text
+/hippocampus/users/policy-administrator
+```
+
+This page gathers everything linked to that user:
+
+- scenarios
+- needs
+- evidence
+- journeys
+- screens
+- decisions
+
+The page is not manually written. It is assembled from the structured source.
+
+## Project Context
+
+The project context page is:
+
+```text
+/hippocampus/project
+```
+
+Use this for overview boards, service maps, policy summaries and other generic project material.
+
+This is separate from research. A project overview may contain useful facts, but it is not the same thing as a research round, participant insight or design action.
+
+Project overview PDFs or decks can be dropped into:
+
+```text
+hippocampus/inbox/project/
+```
+
+Then the team can run:
+
+```bash
+npx hippocampus import project-context
+```
+
+The importer creates a review draft first. After review, promotion adds the material to `hippocampus/source/project-context.json`.
+
+## Relationship Graph
+
+The relationship graph page is:
+
+```text
+/hippocampus/graph
+```
+
+It shows:
+
+- linked entities
+- relationship types
+- how records connect to each other
+
+At the moment, this is a readable list and card view rather than a visual network map. That is deliberate for now: the priority is making the links understandable and trustworthy.
+
+## Trace Tree
+
+The trace tree page is:
+
+```text
+/hippocampus/trace
+```
+
+It lets the team choose any linked thing and move in both directions:
+
+- **What leads here**: earlier research, evidence, scenarios or design inputs
+- **What this leads to**: later insights, actions, screens, decisions or content
+
+This is intended for paths such as:
+
+```text
+old design -> research -> insight -> action -> new design -> content
+```
+
+The trace tree depends on relationships in the knowledge source. If a path is missing, add or import the missing relationship rather than manually drawing the tree.
+
+## Evidence Impact
+
+Evidence impact shows what relies on a piece of evidence.
+
+Example:
+
+```text
+/hippocampus/evidence/evidence-policy-administrators-scenario-map/impact
+```
+
+This helps with questions like:
+
+- If this evidence is weak, what needs reviewing?
+- Which needs depend on this research?
+- Which screens or journeys might need to change?
+- What should we revisit after new research?
+
+This is one of the most useful parts of the graph. It turns evidence from a static reference into something the team can use for design governance.
+
+## Research Import
+
+Research material can be dropped into:
+
+```text
+hippocampus/inbox/research/
+```
+
+Then the team can run:
+
+```bash
+npx hippocampus research sync
+```
+
+The importer looks for new files, creates a review draft and asks before promoting anything into the main knowledge base.
+
+This matters because decks and PDFs are messy. The system should not silently turn extracted text into official design knowledge without review.
+
+## Why This Helps
+
+Hippocampus makes design work easier to inspect.
+
+Instead of separate artefacts saying different things, the team can build from one connected source:
+
+```text
+research
+  -> insight
+  -> need
+  -> scenario
+  -> journey
+  -> prototype screen
+  -> decision
+```
+
+This should make it easier to:
+
+- onboard people into a project
+- explain design decisions
+- review evidence
+- brief agents or collaborators
+- generate handover material
+- understand what changed and why
+
+## What It Does Not Do Yet
+
+Hippocampus does not yet:
+
+- replace research analysis
+- automatically know which insights are important
+- create perfect links without human review
+- show a fully interactive visual graph
+- replace good design judgement
+
+It gives the team a structured memory. The quality still depends on what the team puts into it.