neuroskill-protocols

# NeuroLoop™️ Protocol Repertoire Choose by the **dominant metric signal**. Each entry lists the EEG/biometric trigger and a brief description of what to build in `run_protocol`. Every protocol **must be adapted** to the person using it. Read the Personalisation Engine below before delivering any protocol. --- ## PERSONALISATION ENGINE *(These rules apply to EVERY protocol in this file. The LLM must adapt delivery based on what it knows or can infer about the user. Never deliver a protocol in its generic form when context is available.)* ### Adaptation Dimensions When proposing or running a protocol, actively consider and adapt for: | Dimension | What to adjust | Examples | |---|---|---| | **Age** | Language complexity, duration, physicality, cultural references, playfulness | A 7-year-old gets "pretend you're a robot powering down" not "progressive muscle relaxation". A 75-year-old gets seated-only options and no floor work without asking. | | **Physical ability** | Remove standing/movement if mobility is limited; offer chair, bed, or wheelchair variants | Spinal cord injury → all upper-body or breath-only. Chronic pain → never "tense the painful area". Pregnancy → no breath holds, no prone positions, no Wim Hof. | | **Neurodivergence** | Shorter steps, external timers, sensory preferences, stimming-friendly, no "just focus" | ADHD → gamify, make it competitive, use countdown timers. Autism → warn before sensory changes, offer predictable structure, respect texture aversions. | | **Emotional state** | Tone, pacing, what to avoid | Someone in acute grief does not need "think of 3 things you're grateful for". Someone in rage needs discharge first, not stillness. | | **Cultural background** | Imagery, metaphors, food references, spiritual framing (or deliberate neutrality) | Don't assume everyone meditates, prays, does yoga, eats pork/beef, drinks alcohol, or celebrates the same holidays. Use the user's own language when known. | | **Gender & identity** | Avoid gendered body assumptions; use neutral language unless the user self-identifies | Don't assume chest/breast anatomy, menstrual cycles, or voice pitch. If relevant (e.g. hormonal cycle protocol), ask rather than assume. | | **Professional context** | Environment constraints, time budget, social visibility | A surgeon mid-shift gets 30-second invisible resets not 20-min yoga nidra. A truck driver gets eyes-open only. A teacher gets protocols doable while supervising children. | | **Social context** | Privacy, noise, movement space, other people present | On a crowded train → internal/invisible only. At home alone → full voice, full movement. With a partner → relational variant. With a baby → one-handed, interruptible. | | **Location & time** | Available resources, lighting, temperature, noise, time of day | Outdoors → nature-based anchors. Office → desk-bound. Bedroom at 2 AM → no bright light, no energising. Bathroom → water-based. | | **Language** | Simplicity, jargon avoidance, first-language metaphors | If the user writes in short sentences, mirror that. Never use clinical jargon unless the user is clinical. Respect the user's language and vocabulary level. | | **Need urgency** | Immediate crisis vs. strategic habit-building vs. curious exploration | Panic attack → 30-second physiological intervention, not a lecture. Long-term resilience → weekly practice plan. Casual curiosity → light, no-pressure suggestion. | | **Intimacy level** | How personal, how deep, how vulnerable | New user → surface-level, low-risk protocols. Long-term user who has shared deeply → can go to grief, shame, relational, body image, sexuality. | ### Adaptation Rules 1. **Infer, don't interrogate.** Use available context (time of day, EEG state, conversation history, stated profession, language) to adapt silently. Only ask when essential. 2. **Offer, don't prescribe.** "Would you like to try…" not "You need to do…". Autonomy is sacred. 3. **Name the adaptation.** If you're modifying a protocol for a reason, briefly say why: "Since you're on the train, here's a version you can do without anyone noticing." 4. **Always have a fallback.** If the first suggestion doesn't fit, have a second from a different modality (e.g. if breath doesn't work → tactile; if movement isn't possible → cognitive). 5. **Respect refusal instantly.** If someone says "no" or "not now", acknowledge and move on. Never push. 6. **No spiritual assumptions.** Don't use words like "chakra", "prana", "spirit", "soul", "prayer", "blessing", or "universe" unless the user uses them first or their cultural context makes it clearly welcome. 7. **No body-shaming language.** Never imply the user's body is wrong, broken, or needs fixing. Frame everything as "your nervous system is doing its job, and here's how to work with it." 8. **Age-appropriate intensity.** Children (< 12): playful, short (< 3 min), game-like. Teens (13–19): autonomy-respecting, cool, not preachy. Young adults (20–35): efficiency-oriented, evidence-framed. Middle adults (36–60): practical, time-scarce, habit-aware. Older adults (60+): gentle, dignity-preserving, seated-default, joint-safe. 9. **Hormonal awareness.** Menstrual cycle, pregnancy, postpartum, perimenopause, menopause, testosterone therapy — all affect EEG baselines. Acknowledge when relevant, never assume. 10. **Trauma-informed always.** Never instruct someone to "relax" during a flashback. Never demand eye closure. Always offer "eyes open or closed, your choice." Avoid body-scan in early trauma processing without consent. ### Example Adaptations The same EEG signal (high `bar`, high `stress_index`) might produce: - **Executive in a boardroom:** "Excuse yourself for a water refill. At the sink, run cold water over your wrists for 20 seconds. Come back. Nobody noticed." - **New mother with infant on chest:** "Cup your free hand around the baby's foot — feel the warmth and the tiny weight. That's your anchor. Stay there for 60 seconds." - **14-year-old before an exam:** "Quick game: pick any letter. You've got 30 seconds to name a food, a country, an animal, and a song with that letter. Go." - **Construction worker on break:** "Sit down, grab your cold water bottle, hold it against the back of your neck for 20 seconds. That's the whole protocol." - **80-year-old with arthritis:** "Rest your hands on your lap, palms up. Feel the weight of your hands. Notice the temperature of the air on your palms. That's all." - **Autistic teenager overstimulated at school:** "Headphones on, hood up if you can. Press your tongue hard against the roof of your mouth for 10 seconds. Release. Three times. Nobody sees it." - **Night-shift nurse at 3 AM:** "Gargle your water instead of just drinking it — 15 seconds. Weird, but it flips your vagus nerve on. Instant alertness." - **Grieving person:** "You don't need to do anything right now. Just put one hand on your chest. Feel the warmth of your own hand. That's enough." - **Someone with ADHD struggling to start a task:** "Race yourself: open the document and type the worst possible first sentence. You have 10 seconds. Go. It doesn't have to be good — it has to exist." - **Pregnant woman in third trimester:** "Seated only, no breath holds. Gentle ear massage — slow circles on the soft part right in front of the ear canal. 60 seconds per side." - **Person in a wheelchair:** "Roll your shoulders back slowly, squeeze the shoulder blades together, hold 5 seconds. Your upper body holds the same stress patterns — this releases them." - **Someone who speaks English as a second language:** Use short sentences. Simple words. No idioms. "Close your eyes. Press your hands together hard. Hold. Let go. Feel the warmth." --- ## API INTEGRATION GUIDE *(The NeuroSkill API provides real-time EEG data, voice guidance, notifications, labels, timers, hooks, sleep staging, session comparison, and neural similarity search. Every protocol should leverage these tools to create a closed-loop, data-driven experience — not just deliver static instructions.)* ### Protocol Lifecycle Every protocol has four phases. Use the API in each: ``` ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │ BEFORE │ ──→ │ DURING │ ──→ │ AFTER │ ──→ │ LONGITUDINAL │ │ Validate │ │ Guide │ │ Measure │ │ Track & Trigger │ │ & Baseline │ │ & Monitor │ │ & Reflect │ │ Across Sessions │ └─────────────┘ └─────────────┘ └──────────────┘ └──────────────────┘ ``` ### BEFORE — Validate Trigger & Baseline Before proposing or starting ANY protocol, check the live EEG state to confirm the trigger condition actually exists and capture a baseline. | Action | API Call | Purpose | |---|---|---| | **Check live state** | `{"command": "status"}` | Verify the metric trigger (e.g. confirm `bar` is actually high before offering Box Breathing) | | **Get session context** | `{"command": "sessions"}` | Know how long they've been recording, when the session started | | **Check signal quality** | `status → signal_quality` | Don't run a protocol if signal is poor (< 0.7) — recommend headband adjustment first | | **Baseline snapshot** | `status → scores` | Capture pre-protocol values of key metrics to compare after | | **Search for precedent** | `{"command": "search_labels", "args": {"query": "box breathing"}}` | Check if they've done this protocol before and how it went | | **Label the start** | `{"command": "label", "args": {"text": "protocol start: box breathing", "context": "bar=0.72, stress_index=68, trigger: high stress"}}` | Timestamp the protocol start with baseline metrics for later analysis | **Example — before starting Box Breathing:** ```json // 1. Check if stress is actually elevated {"command": "status"} // → scores.bar = 0.72, scores.stress_index = 68 → confirmed, proceed // 2. Check if they've done this before {"command": "search_labels", "args": {"query": "box breathing", "k": 5}} // → 3 prior sessions found, average relaxation increase of +0.15 → mention this // 3. Label the start {"command": "label", "args": {"text": "protocol start: box breathing 4-4-4-4", "context": "bar=0.72, stress_index=68, relaxation=0.31"}} // 4. Start timer if timed protocol {"command": "timer"} ``` ### DURING — Guide & Monitor Use voice, notifications, and real-time data to guide the protocol and provide live biofeedback. | Action | API Call | Purpose | |---|---|---| | **Voice guidance** | `{"command": "say", "args": {"text": "Inhale... 2... 3... 4..."}}` | Hands-free, eyes-closed guidance. Essential for breath, meditation, body scan protocols | | **Step notifications** | `{"command": "notify", "args": {"title": "Next step", "body": "Now exhale slowly for 8 counts"}}` | Visual cue for step transitions when voice is inappropriate | | **Real-time monitoring** | `{"command": "status"}` (poll every 30–60s) | Track metric changes mid-protocol. Adapt: "Your alpha just rose — whatever you're doing, keep going" | | **Mid-protocol label** | `{"command": "label", "args": {"text": "alpha spike during body scan"}}` | Mark notable moments for later analysis | | **Live feedback to user** | Check `status → scores` mid-protocol | "Your relaxation score just jumped from 0.31 to 0.52 — the breathing is working" | | **Focus timer** | `{"command": "timer"}` | For timed protocols (Pomodoro, meditation, focus blocks) | | **DND activation** | `{"command": "dnd_set", "args": {"enabled": true}}` | Protect the user from interruptions during meditation or deep work protocols | **Example — during a 5-minute Cardiac Coherence protocol:** ```json // Minute 0: Start {"command": "say", "args": {"text": "Let's begin cardiac coherence. Breathe in for 5 seconds."}} {"command": "dnd_set", "args": {"enabled": true}} // Minute 0:05 {"command": "say", "args": {"text": "Now breathe out for 5 seconds."}} // Minute 1: Check progress {"command": "status"} // → rmssd rising from 28 to 34 → good sign {"command": "say", "args": {"text": "Good. Your heart rhythm is already smoothing out. Keep going."}} // Minute 2:30: Mid-point check {"command": "status"} // → relaxation 0.31 → 0.48 {"command": "say", "args": {"text": "Halfway there. Your relaxation is climbing. Stay with the rhythm."}} // Minute 5: End {"command": "say", "args": {"text": "That's 5 minutes. Well done. Sit quietly for a moment."}} {"command": "dnd_set", "args": {"enabled": false}} ``` ### AFTER — Measure & Reflect Immediately after a protocol, capture the post-state and show the user what changed. This is the most powerful moment for motivation and learning. | Action | API Call | Purpose | |---|---|---| | **Post-protocol snapshot** | `{"command": "status"}` | Capture post-protocol metrics | | **Label the end** | `{"command": "label", "args": {"text": "protocol end: box breathing", "context": "bar=0.48, stress_index=42, relaxation=0.58 — delta: bar -0.24, stress -26, relax +0.27"}}` | Record the outcome with deltas | | **Compare before/after** | Compare baseline snapshot to current `status` | Show concrete numbers: "Your stress index dropped from 68 to 42. Your relaxation rose from 0.31 to 0.58." | | **Session trend** | `{"command": "session_metrics", "args": {"start_utc": ..., "end_utc": ...}}` | Show first-half → second-half trends for the session | | **Voice the results** | `{"command": "say", "args": {"text": "Your stress dropped 38 percent. Relaxation nearly doubled."}}` | Make the data tangible | | **Notify summary** | `{"command": "notify", "args": {"title": "Box Breathing Complete", "body": "Stress: 68→42 (-38%). Relaxation: 0.31→0.58 (+87%)"}}` | Persistent summary the user can see later | **Example — after Box Breathing:** ```json // 1. Get post-state {"command": "status"} // → bar=0.48, stress_index=42, relaxation=0.58 // 2. Label with full delta {"command": "label", "args": {"text": "protocol end: box breathing 4-4-4-4", "context": "Duration: 5min. bar: 0.72→0.48 (-33%), stress_index: 68→42 (-38%), relaxation: 0.31→0.58 (+87%)"}} // 3. Tell the user {"command": "say", "args": {"text": "Nice work. Your stress index dropped 38 percent, from 68 to 42. Relaxation nearly doubled. That's a strong response."}} // 4. Persistent notification {"command": "notify", "args": {"title": "✓ Box Breathing Complete", "body": "Stress: 68→42. Relaxation: 0.31→0.58. Duration: 5 min."}} ``` ### LONGITUDINAL — Track Across Sessions & Auto-Trigger The most powerful use of the API is building a personal history of protocol effectiveness and setting up proactive triggers. | Action | API Call | Purpose | |---|---|---|