BrainScribe developer specification.

Client file & intake

One record per person. Demographics captured once, conditioning every scale, score and draft that follows. Field-level visibility is layered: smart defaults show what this assessment needs; optional sections expand when the case calls for them.

Required field set

Optional sections (lazy-loaded)

Education & vocation banding

Banding harmonises premorbid estimates and removes free-text noise. Drawn from the Hollingshead Four-Factor framework, adapted to Australian education stages and ANZSCO occupational skill levels.

Education · 8 bands

Vocation · 8 bands (ANZSCO-aligned)

Appointment scheduling, consent & release of information

Scheduling, electronic consent for telehealth and recording, and release-of-information capture, all in the same workspace. Booking a session creates an appointment object that issues the consent paperwork and the secure session link in one transaction. The three session-related consents — telehealth, video recording, transcript — are independently revocable.

Consent objects

Signature record

// stored per consent object
{
  "client_id": "A8C2",
  "object": "consent.telehealth",
  "version": "2026-03",            // versioned wording
  "signed_at": "2026-03-22T14:08:00+10:00",
  "signed_via": "email_link",         // or in_clinic
  "signer_ip": "110.143.x.x",
  "signer_useragent": "…",
  "signature_hash": "sha256:…",
  "witness": null
}

Scale administration channels

Every scale, every channel. On-site (PC, phone, tablet, iPad), or by unique link emailed to the patient or to an informant — with distinct wording, distinct return path and distinct response storage.

Channel matrix

Required uniqueness

Result flow

On completion the platform:

1. Stores raw responses, computed scale score, percentile and z (where applicable) on the assessment record.
2. Logs time_to_complete_seconds and pause_count.
3. Emails the clinician a broad result, with a platform link. Detail requires the clinician's platform password.
4. If cc_client_broad_result = true, sends the client a broad, plain-language summary with the instruction "discuss with your clinician at your next appointment".
5. If any high-risk trigger fires (see §6), promotes the notification to priority and surfaces a banner in the clinician dashboard.

Notifications, reminders & passwords

Auto-reminders sent until completion or window expiry. Detail access gated behind the clinician's platform password. Broad results may be cc'd to the client, full results may not.

Reminder cadences (clinician-configurable)

Password & access rules

• Clinician platform password rotates every 90 days; minimum 14 chars, passphrase-friendly.
• 2FA required for full-result view from a new device.
• cc-to-client option ships only the broad result; never percentile, z, or item-level responses.
• Email notifications never contain identifying clinical content. They contain: client initials, scale name, completion status, link to platform.

High-risk flags

Priority-review triggers raise the result to the top of the clinician's queue and surface a banner. They never substitute for clinical judgement, but they ensure the clinician sees the right result first.

Notification path

1. Email + in-platform notification, marked priority.
2. If clinician unread for priority_escalation_window (default 4 h, business hours), escalation rule fires — second clinician on the practice escalation list is notified.
3. Banner persists on the client record until reviewed and acknowledged by the clinician.

Assessment builder

Practitioner builds the assessment from client-file context (referral reason, background, prior scales). System suggests scales and tests; practitioner chooses; practitioner enters raw and standardised scores against selected norms.

Suggestion model inputs

Score entry contract

// each performance-test entry
{
  "test_code": "WAIS5_DSF",
  "norm_set": "AU_2024_age_education",
  "raw": 36,
  "scaled": 11,         // optional, derived if absent
  "z": 0.33,
  "t": 53,
  "percentile": 63,
  "qualitative": "average",
  "administered_at": "2026-03-25T10:14:00+10:00",
  "entered_by": "clinician_id"
}

The platform validates that raw is within the test's allowed range and that derived metrics (z, t, percentile) reconcile to within rounding tolerance. Conflicting entries trigger a soft warning, not a hard error — the clinician may have a reason.

Context dimensions

• context.purpose · diagnostic · capacity · forensic · educational · screening · monitoring
• context.reader_level · lay · referring GP · specialist (neurologist, geriatrician) · legal · expert
• context.tone · clinical · plain-language · medico-legal

Report drafting & reader tuning

The report is assembled, not generated. Each section is built from named inputs the clinician can inspect. Output features and styles customisable without a pre-determined menu of "report templates".

Reader tuning surface

Section provenance

// per drafted section
{
  "section": "cognitive_profile",
  "inputs": [
    "score:WAIS5_DSF",
    "score:CVLT3_DELAYED",
    "observation:fluent_speech",
    "transcript:span(11:42-12:18)"
  ],
  "reader_level": "specialist_medical",
  "version": 3,
  "clinician_edited": true
}

Practitioner-preference learning

The platform learns each clinician's voice — preferred phrasing, section ordering, sentence length, framing of qualitative results, formulation style — and applies it to subsequent drafts.

Signal capture

• Edit-distance between drafted and final text, per section, per scale.
• Insert / delete patterns on heading words, transition phrases, hedging language.
• Reordering of domain sections.
• Length deltas after clinician edit.
• Explicit preferences (template-level toggles).

Application

Preferences apply at the clinician scope, with optional roll-up to the practice (Clinic tier). Preferences are never applied to clinical content (scores, percentile boundaries, qualitative descriptors) — they apply only to phrasing, structure and framing.

Data model & record contract

A single assessment_record object aggregates client file, scales, scores, telehealth artefacts, transcript spans, observations and drafted sections. Every field is dated, attributed and versioned.

Top-level shape

assessment_record {
  id: "A8C2-v3",
  client_id: "A8C2",
  context: { purpose, reader_level, tone, specialty },
  scales: [] ScaleAdministration,
  scores: [] PerformanceTestScore,
  telehealth: [] SessionArtefact,
  transcript: TranscriptArtefact,
  observations: [] ClinicianObservation,
  consent: [] ConsentObject,
  draft: ReportDraft,
  audit: AuditTrail
}

Audit trail invariant

Every mutation appends to audit with (field, before, after, actor, timestamp, source). Audit records are append-only and exported with the report on request.

Front-facing site vs backend spec

A note on what we show on the marketing site and what we keep in this document.

On the marketing site

• Capability — that BrainScribe captures the client file, runs scales on every channel, captures consent, and drafts the integrated report.
• Concrete UI fragments — one intake-form mock, one source-to-draft trace, one telehealth scene. Enough to make the product real without enumerating every field.
• Reassurance — privacy, identifier substitution, clinician authorship, Australian focus.
• One link — to this dev spec, for partners and engineers.

In this developer specification

• Every field name, type and required flag.
• Banding tables (education, vocation, parental).
• Channel matrix, token rules, password & cc policy.
• High-risk triggers and escalation paths.
• Score-entry contract, reader-tuning surface, section provenance.
• Preference-learning signal capture and firewall.
• Top-level data shape and audit-trail invariants.

Marketing copy answers "what will this do for my Saturday?". This document answers "how do we build it so the answer is true?".