Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Spec authoring — how we create TEDY specifications

We reverse-engineer specifications for the reference-editor rewrite from the existing, working reference platform product, then align them to the Helex EMR specification system. The specs are the contract the React modules are (re)built against.

Alignment with the EMR spec system

We follow the EMR spec rules verbatim — do not invent a parallel system:

  • Rules: /Users/igor/source/emr/docs/specifications/rules.md (spec-first, lifecycle Proposed→Accepted→Verified→Implemented, mandatory frontmatter + sections, glossary gate, data-model + FHIR-mapping + API-contract rules).
  • Templates: /Users/igor/source/emr/docs/specifications/_templates/ — pick one per spec: resource-list, resource-create, resource-management, import-tool, tool-feature (+ the two clinical ones we don’t use).
  • Validation: the EMR spec-validation skill / validate-spec command.

TEDY specs live here under specs/tedy/ (see specs/tedy/README.md for IDs). They may be contributed upstream into emr/docs/specifications/ (module prefix TRM, “terminology, via the reference platform”) once accepted — keep them template- and frontmatter-compatible so that move is mechanical.

The two-step derivation

Because the source of truth is a shipped app, every spec is derived in two ordered passes. Pass 1 captures what the product actually does; pass 2 makes it precise and contract-complete.

Step 1 — Scan the live product on dev-tx.example (Claude Chrome)

Drive the real the reference platform UI and record observed behaviour per page. For each screen capture:

  • Route (reference-editor path, e.g. /resources/code-systems) and page title.
  • Layout: search box, primary actions (e.g. Add code system → Manual / Import FHIR), column-config + filter toggles, side panels.
  • Table: column order + labels + which cells are links (e.g. ID · LAST VERSION · TITLE · PUBLISHER · STATUS · COUNT), row expand, status chips + their values.
  • Filters: each field + control type (publisher, status, space, …).
  • Detail / tabs, empty & error states, and the visible i18n labels (note the active language).

Tools: navigate + screenshot + read_page (accessibility tree) on https://dev-tx.example/... (guest). Output: a raw observed-behaviour note per page (drop screenshots under specs/tedy/_scans/). Do not write contracts yet — only what is observable.

This pass is authoritative for actual UX (what users see and do). It is not authoritative for API shapes, params, permissions, or validation — those aren’t fully observable from the UI.

Step 2 — Reconcile against source, then fix differences

Open the implementation and upgrade the draft into a real spec, fixing any difference from Step 1:

  • reference-editor (<reference-editor-src>) — the component + service for the page: exact columns/params, search params, sort keys, privileges (*.CodeSystem.write), statuses, validation, actions, sub-routes. reference-editor is authoritative for behavioural detail the UI hides.
  • terminology-server (<terminology-server-src>) — the API endpoints (/ts/*), request/response envelopes ({data, meta}), error contract, data model (tables, cardinality), and FHIR mapping. Authoritative for contracts + model.
  • Record every live-vs-source difference in a ## Differences note (live wins for UX; source wins for contracts; flag genuine bugs/drift).

Then write the spec with the chosen template: fill the mandatory sections (Description+wireframe, Glossary Terms, Business Feature Sitemap, Data Model, Sitemap/Navigation, API Endpoints, Security/Permissions, NFRs, Business Tests, Source Code References, Traces), set state: Proposed, and populate source-refs with both origins:

  • reference-editor/terminology-server paths (behavioural + contract origin), and
  • the TEDY React implementation (helex-tx module/lib paths) as the rebuild target.

traces-from points to a user story; if none exists yet, note it as a gap (EMR rules require a story before a solution spec — create a thin story or mark Proposed pending one).

Order of work

Each resource is a feature family (MDM pattern): a TEDY.NN overview/common spec (tool-feature) that owns the shared data model / value sets / FHIR mapping / privileges / API surface / navigation, plus child screens TEDY.NN.1 List, TEDY.NN.2 Add, TEDY.NN.3 View (children reference the root, no duplication). Start with the resources already built in TEDY (Code Systems — see the TEDY.01 family) so spec and code cross-check, then move to Value Sets, Map Sets, etc.

Checklist per spec

  1. Step 1 live scan recorded (screens + observations, _scans/).
  2. Step 2 source reconcile done; ## Differences captured.
  3. Template chosen; all mandatory sections filled; glossary terms mapped.
  4. Frontmatter complete; source-refs = reference-editor/-server and TEDY paths.
  5. Data model + FHIR mapping + API/error contract per EMR rules.
  6. Business tests written (before implementation, for un-built resources).
  7. Passes the EMR validate-spec check.