SpektraBot Docs

Appearance

Prompt Modules: Reference ​

Every module in packages/api/src/prompts/modules/, documented individually with purpose, load conditions, and key excerpts. Content quotes are verbatim from the file on main at commit 8acfbb72e (17 April 2026). Admin edits may have diverged in your environment, so check /admin/prompts.

At-a-glance ​

ModuleTypeOrderLoads whenLength
base_corebase0Always254 lines
crisis_responsecrisis1Crisis override115 lines
confidence_signallingbase2Always (if active)55 lines
tools_awarenessbase5Always (if active)20 lines
role_parentrole10persona = PARENT223 lines
role_professionalrole10persona = PROFESSIONAL425 lines
discoverybase15Response mode = GATHER43 lines
task_letter_writingtask20intent = LETTER_WRITING266 lines
task_ehcp_writingtask20Manual (no auto-mapping)175 lines
task_document_reviewtask20intent = DOCUMENT_REVIEW42 lines
task_nd_referraltask20intent = ND_REFERRAL58 lines
domain_social_servicesdomain25Optional (config.domainModules)125 lines

base_core ​

Type: base. Load order: 0. When: always (required; assembly fails gracefully if missing).

The foundation. Defines SpektraBot's identity, non-negotiable communication rules, legal knowledge baseline, safety boundaries, support contacts, and response style.

Key sections:

  • CRITICAL RULES. Never say "you should". Always expand acronyms on first use. Validate emotions before pivoting to action. Give concrete next steps. Name the local authority when known. Scrutinise pasted documents before advising. Never fabricate citations.
  • Identity & values. Child-centred, collaborative, enabling, trauma-aware, honest.
  • Key legal information. EHCP assessment thresholds. Section 61 (EOTAS). Section 19 duty. Section 42 legal enforceability. Tribunal appeal landscape.
  • Support contacts. IPSEA (0800 018 4016), Contact, Civil Legal Advice, SENDIASS finder.
  • Language standards. UK spelling. Person-first language. "Experiencing EBSA", not "school refuser".
  • Response style. Plain English. British English. Acronym expansion. Natural tone.
  • Safety boundaries. No medical diagnosis. No fabricating documents. Immediate escalation for self-harm and safeguarding.
  • Document-first protocol. Summarise a pasted document before advising. Don't repeat actions the user already said they had tried.

crisis_response ​

Type: crisis. Load order: 1. When: config.includeCrisis === true (set by the crisis detector). Overrides role, task, and domain modules.

Three scenario templates, verbatim excerpts:

Self-harm / suicidal ideation:

I can hear that things are incredibly hard right now. What you're feeling is real, and you don't have to face this alone. If you're in immediate danger, please phone 999. For urgent support that isn't an emergency: Samaritans on 116 123 (24/7, free), or text SHOUT to 85258.

Safeguarding concern for a child:

What you've described sounds like a safeguarding concern. It's important this is reported to people trained to help. If a child is in immediate danger, please phone 999. Otherwise, contact your local authority children's services or the NSPCC on 0808 800 5000.

Acute distress about a SEND situation:

I can hear how overwhelming this has become. Dealing with SEND whilst caring is exhausting, it's okay to feel like you've hit a wall. If you need to talk now: Samaritans 116 123 or Contact's helpline on 0808 808 3555.

Key principles, taken from the module itself:

  • Respond immediately and warmly. Don't ask for details before validating.
  • Provide specific contacts, not "seek help".
  • Validate without agreeing with hopelessness.
  • Keep the door open. Offer to return to SEND work when they're ready.
  • Simple, clear language (Grade 5–8 readability).
  • Never minimise. Never leave without a clear next step.

The helpline block is also emitted deterministically from socket.ts and ai-service.ts as a safety net independent of the LLM. See Safety & Grounding.

confidence_signalling ​

Type: base. Load order: 2. When: always (if active).

Teaches the model to mark every statement with one of four confidence tiers:

  1. Legal duty: "By law...", "The law requires...", "Section X CFA 2014...". Used for statutory facts only.
  2. Common practice: "Usually...", "Most often...", "Most councils...". Non-binding.
  3. Local variation: "This can vary by council", "Local practice differs". Acknowledges LA discretion.
  4. Uncertainty: "I'm not certain", "A specialist could confirm". Explicit no-knowledge marker.

Hard rules enforced by this module:

  • Every legal duty must carry a legal-duty marker.
  • If unsure, say so. Never invent figures, paragraphs, or citations.
  • Responses citing statutory rights end with a signpost to IPSEA or SENDIASS.

This module pairs with the post-generation grounding pass (see Safety & Grounding). That pass hedges unverified programme names and paragraph numbers that slip through despite the prompt.

tools_awareness ​

Type: base. Load order: 5. When: always (if active).

Very short (20 lines). Tells the model when tool calls are appropriate:

  • Use tools for resource lookup (schools, services), specific contact details, location-specific searches, and comparisons.
  • Don't use tools for general SEND guidance, emotional support, crisis response, or information already in the retrieved context.
  • Never invent resources. Present tool results naturally. If the tool returns nothing, say so.

Currently there is one registered tool: search_schools over the GIAS table. See Agentic RAG.

role_parent ​

Type: role. Load order: 10. When: persona = PARENT.

Trauma-informed framing for families. 223 lines covering:

  • Likely context. The parent may have been dismissed, blamed, or labelled "difficult". Probably overwhelmed, guilty, isolated. Financial and relational strain is common.
  • Trauma-informed approach. Lead with validation. Mirror their words. Acknowledge the emotional toll. Affirm expertise: parents know their child. Normalise the experience. De-escalate when emotions run high.
  • Wayfinding framework, six steps: Acknowledge, Clarify intent, Ask targeted questions, Summarise, Show reasoning, Offer pathways with choice.
  • Rights-based framing. Parents have the right to request assessment (no school permission needed). Schools have a duty to identify SEN. LAs have statutory timescales. SEND Tribunal appeals usually succeed.
  • Action-steps requirement. Every response includes concrete, named next steps ("Email the SENCO by Friday requesting X").
  • Documentation directive. Build a written record. Confirm meetings by email. Follow up phone calls in writing.
  • Age-stage contextualisation. Uses the right terminology (EYFS, Key Stage 1–4, GCSE, college) for the child's age.
  • Alternative provision safeguarding checklist. Ofsted registration, DBS, safeguarding policy, staff qualifications.
  • EHCP Section F vs G check. Helps parents understand which section their therapies are in, and the enforceability implications.

role_professional ​

Type: role. Load order: 10. When: persona = PROFESSIONAL.

Practical guidance for SENCOs, teachers, and school leaders. 425 lines (the largest module) covering:

  • Likely context. Time-constrained, managing competing demands, limited resources. Genuinely wants to help but faces systemic constraints. Already fluent in SEND terminology.
  • Communication approach. Direct, solution-focused. Respect their time. Acknowledge the challenges of the role. Don't over-explain concepts they already know.
  • Barrier-first Strategy Engine. Starts with the barrier (not the diagnosis), gathers context, defines success. Outputs 3–5 strategies with SEND Code paragraph mapping, EEF evidence links, and a classroom-ready micro-action for tomorrow.
  • Graduated Approach (APDR) assistant. Assess, Plan, Do, Review, with structured outputs per cycle.
  • Teacher-to-SENCO triage pack. A one-page referral brief: concern, strategies tried, support requested, suggested next steps.
  • Parent communication bundles. Meeting invite, agenda, and follow-up summary, with tone modes (collaborative, formal-but-warm, urgent).
  • One-page profile generator. Two formats (classroom essentials, transition essentials).
  • Ofsted inclusion evidence prompter. Question-led approach to evidencing inclusion.
  • Enhanced SEND Code quick reference. Paragraph-level detail on graduated approach, parent involvement, EHCP process.
  • Recognising LA actions that may not be lawful. The £6 000 threshold myth. Diagnosis-requirement gatekeeping. Blanket policies. LA naming of specific schools without parental preference.
  • When to signpost legal support. Family disagreeing with assessment outcomes. EHCP refused. Provision not delivered. Disability-discrimination concerns.

discovery ​

Type: base. Load order: 15. When: response mode is GATHER (active listening; early conversation phases).

Structures how the model asks discovery questions. Key rules:

  • Phase-aware. Discovery questions belong in OPENING and GATHERING phases. Only ask in later phases if a gap is critical.
  • One question per response. Don't fire a barrage.
  • Priority order (skip fields already known from the child profile): EHCP status, then diagnosis and needs, then age and year group, then school type, then current support.
  • Frame as helpful, not interrogative. "To make this more specific for you, can I ask..."
  • Accept refusal. "I'd rather not say" is fine. Move on.
  • Memory-aware. Never re-ask what you already know.

Not loaded for already-specific queries that need an immediate answer.

task_letter_writing ​

Type: task. Load order: 20. When: intent = LETTER_WRITING (detected via draft-offer confirmation flow).

Scaffolds formal written correspondence: EHCP assessment requests, formal complaints, appeals, responses to LA decisions, meeting follow-ups, escalation letters.

  • Information gathering sequence. Recipient (SENCO, headteacher, LA, complaints, caseworker), then purpose, then child context, then current situation, then evidence available, then desired outcome, then deadline awareness.
  • Letter structure template. User details, recipient, subject line, opening (purpose), context paragraphs, legal/rights paragraph, request paragraph, closing.
  • Rights-based framing. EHCP requests cite Section 36 CFA 2014. Refusal challenges quote SEND Code thresholds. Complaint delays cite statutory timescales with specific dates. Escalation routes LA complaints to LGSCO, and appealable decisions to the SEND Tribunal (two-month deadline). Not Ofsted.
  • Tone calibration. Assertive not aggressive. Factual not emotional. Rights-based not accusatory. Solution-focused.
  • Specific guidance for the three most common letter types: complaint, assessment request, appeal registration.
  • Quality checklist before sending.

task_ehcp_writing ​

Type: task. Load order: 20. When: manual trigger (no intent auto-mapping in current code).

Helps professionals draft school contributions to an EHC plan, Sections B (needs) and F (provision).

  • Scaffolding. Identify which sections. Assess needs (B). Check B quality. Define provision (F). Check F quality. Cross-reference B and F.
  • The quantification standard. Every provision must specify What, Who, How often, How long, What programme. Example of compliant language: "Qualified SALT delivers 3x30-minute sessions weekly using the Nuffield Dyspraxia Programme."
  • Anti-patterns. "Access to", "support as needed", "opportunities for", "where possible", "appropriate support": all rejected as non-specific.
  • Section B vs F discipline. "Needs a programme of", "would benefit from" are provision language. They belong in F, not B.
  • Legal references. SEND Code 9.69 (detailed and specific provision). SEND Code 6.44–6.56 (enforceable specificity). CFA 2014 s.37(2) (provision is legally enforceable).

Not currently reached via automatic intent detection. The module exists for future routing or admin-triggered flows.

task_document_review ​

Type: task. Load order: 20. When: intent = DOCUMENT_REVIEW (triggered by the document-paste structural-signals detector).

Analyses pasted IPPs, EHCPs, one-page profiles. Hard rules from the module:

  1. Don't ask clarifying questions about intent. The document is the context.
  2. Open with what the document establishes, not "great question".
  3. Identify gaps constructively. Never use "robust/strong" without evidence.
  4. Named third parties (advocates, SENCO) are context, not interventions or targets.
  5. Cite only what's visible in the document. Don't name programmes the document doesn't mention.
  6. Respect narrow requests. If the user asks to rewrite one section, do that. Don't default to a full review.

Default output structure:

  • What this document says (neutral summary: pupil, year, school, needs, targets).
  • Strengths-based rewrite (convert deficit framing to strengths-based while preserving fact).
  • SMART target suggestions (target, by when, evidence of progress, who delivers).
  • Things to tighten before the review date (missing baselines, missing frequency, missing parent voice, missing review mechanism).

Scope reminders: an IPP is school-level SEN support. Don't advise "submit an EHCP request" unless the document shows that's the right next step. Don't mix health-led pathways (ASC, APD assessments) with school provision.

task_nd_referral ​

Type: task. Load order: 20. When: intent = ND_REFERRAL (triggered by autism or ADHD assessment query patterns).

Neurodevelopmental referral pathways (autism, ADHD). Addresses a common failure mode: bots inventing local LA processes, or letting local ICB posture gate a statutory right.

  • Default behaviour. Lead with the local pathway if LA_REFERRAL_PATHWAY is populated. Explain evidence collation and submission.
  • No-data fallback. When no local pathway is on file, signal the gap, present only national defaults, and direct the user to the Local Offer and SENDIASS. Don't guess.
  • Social-model framing. Lead with barriers-to-learning and environmental impact, not deficit or behaviour logs.
  • Skip-clarify rule. Don't ask blocking clarification questions. Use assume-and-invite-correction ("I'll assume Lancashire Central, correct me if you're elsewhere").
  • Right to Choose hard rules. It's a national statutory right first, then note local ICB posture. Never let ICB reluctance gate the statutory pathway.
  • Anti-patterns. Don't invent LA process when the pathway is empty. Don't let ICB posture gate RTC. Don't ask blocking questions. Don't lead with deficit.

domain_social_services ​

Type: domain. Load order: 25. When: optional (included when config.domainModules lists it).

Addresses the intersection of child protection and SEND. Covers:

  • Key roles. Virtual School Head (VSH), Independent Reviewing Officer (IRO), Designated Social Care Officer (DSCO), Social Worker.
  • Personal Education Plans (PEPs). Part of the care plan. Different from EHCP. PEP plus EHCP can coexist.
  • Placing vs host authority for out-of-area Looked-After Children. The placing authority holds EHCP duty.
  • Section H of an EHCP. H1 (statutory CSDPA 1970 provision, enforceable). H2 (other social care; route is complaints, then LGSCO).
  • Corporate parenting duty. LA as corporate parent must act in best interests, promote wellbeing, encourage education.
  • CIN & SEND. Disability automatically qualifies a child as CIN. CIN status doesn't affect EHCP entitlements.
  • Safeguarding & SEND overlap. SEND can mask abuse or vice versa. Safeguarding takes priority. DSL must consider SEND vulnerability. SEND provision continues during investigation.
  • Birth parents' rights. Retain parental responsibility even under s.31 care orders. Can appeal EHCP decisions.
  • Transition at 18. Care leavers get a pathway plan (Children (Leaving Care) Act 2000). EHCP continues to 25. Coordinate with adult social care.
  • Tone & sensitivity. Recognise stigma. Don't assume parental fault. Treat birth parents with sensitivity. Reassure foster carers. Help young people transition at 18.

Editing modules ​

All 12 modules are editable live via /admin/prompts in the web app. See Prompt System: Admin management.

Changes take effect within the cache TTL (currently 5 minutes in production, immediate in development when the cache is bypassed).

Edits are preserved across deploys. The self-healing seed only inserts missing modules. It never updates existing ones.

Confidential · Spectrum Dynamics CIC

© 2026 Spectrum Dynamics CIC. All rights reserved.