neuroskill-evidence

# NeuroSkill Evidence Collection *(This skill defines how the LLM silently collects, aggregates, and uses evidence about what actually helps each person. Every other skill that delivers an intervention, tracks a habit, or makes a recommendation should follow these rules.)* --- ## Core Principle **Every intervention is a natural experiment.** The EEG headband is already running. The baseline already exists. The post-state will arrive automatically. All the LLM needs to do is snapshot, label, and remember. The user should NEVER be asked: "Can I label this?" or "Should I measure the outcome?" Just do it. The labeling and measurement are invisible infrastructure. The only thing the user sees are the insights that emerge over time. **The goal is population-of-one science.** Not "does box breathing reduce stress in general?" but "does box breathing reduce stress for YOU, at THIS time of day, in THIS context, compared to THESE alternatives?" --- ## Who Uses This Skill Every skill that does any of the following MUST follow the evidence collection rules: | Skill | How it uses evidence | |---|---| | **neuroskill-protocols** | Label every protocol execution (start + end + deltas). Rank protocols by personal effectiveness. Select proven winners. | | **neuroskill-hooks** | Label hook trigger events. Track whether the user acted on the hook and whether it helped. Tune thresholds from real outcomes. | | **neuroskill-streaming** | Label calibration sessions. Track TTS-guided protocol outcomes. | | **neuroskill-sessions** | Correlate session-level metrics with labeled interventions. Identify which sessions had protocols and which didn't. | | **neuroskill-search** | Use `px:` labels to find past interventions and correlate with neural similarity search results. | | **neuroskill-labels** | The evidence system IS the label system. All `px:` labels flow through `label` and `search_labels`. | | **neuroskill-sleep** | Label evening routines. Correlate sleep architecture with pre-sleep interventions. | | **neuroskill-dnd** | Label DND activations. Track whether protected focus periods produced better outcomes. | | **neuroskill-screenshots** | Correlate screen content (apps, sites) with brain state changes when labeled. | | **neuroskill-llm** | The LLM is the evidence engine — it creates labels, queries them, aggregates, and recommends. | | **neuroskill-recipes** | Recipes can incorporate evidence queries for automation scripts. | --- ## Standardised Label Schema ### Prefix System All evidence labels use the `px:` prefix (protocol/experience execution): | Prefix | Meaning | Example | |---|---|---| | `px:start:<name>` | Intervention began | `px:start:box_breathing` | | `px:end:<name>` | Intervention ended | `px:end:box_breathing` | | `px:note:<name>` | Observation (no start/end pair) | `px:note:poor_sleep` | | `px:skip:<name>` | Offered but declined | `px:skip:kapalabhati` | | `px:auto:<name>` | Auto-triggered by hook | `px:auto:stress_alert` | The `px:` prefix makes all evidence data instantly queryable: ```json {"command": "search_labels", "args": {"query": "px:end", "k": 50}} {"command": "search_labels", "args": {"query": "px:end:box_breathing", "k": 20}} {"command": "search_labels", "args": {"query": "px:start", "k": 50, "mode": "context"}} ``` ### Context Format The `context` field uses pipe-separated `key=value` pairs for machine-parseable structured data: ``` modality=breath | trigger=high_bar | bar=0.72 | stress_index=68 | relaxation=0.31 | focus=0.45 | hr=78 | mood=0.40 | faa=-0.03 | rmssd=26 ``` ### Required Fields **Start label context — always include:** | Field | Description | Example | |---|---|---| | `modality` | Intervention type | `breath`, `tactile`, `cognitive`, `visual`, `movement`, `auditory`, `passive_physio`, `music`, `dietary`, `relational`, `environmental` | | `trigger` | EEG trigger that prompted this | `high_bar`, `low_focus`, `low_rmssd`, `high_drowsiness`, `low_mood`, `high_cognitive_load`, `user_request` | | `bar` | Beta/Alpha Ratio at start | `0.72` | | `stress_index` | Stress index at start | `68` | | `relaxation` | Relaxation score at start | `0.31` | | `focus` | Focus score at start | `0.45` | | `hr` | Heart rate at start | `78` | | `mood` | Mood score at start | `0.40` | | `faa` | Frontal Alpha Asymmetry at start | `-0.03` | | `rmssd` | HRV (RMSSD) at start | `26` | **End label context — always include (in addition to the above at end-state):** | Field | Description | Example | |---|---|---| | `duration_min` | Duration in minutes | `5` | | `delta_bar` | Change in BAR | `-0.24` | | `delta_stress` | Change in stress_index | `-26` | | `delta_relaxation` | Change in relaxation | `+0.27` | | `delta_focus` | Change in focus | `+0.07` | | `delta_hr` | Change in heart rate | `-10` | | `delta_mood` | Change in mood | `+0.15` | | `delta_faa` | Change in FAA | `+0.04` | | `delta_rmssd` | Change in RMSSD | `+12` | | `outcome` | Overall result | `positive`, `neutral`, `negative` | ### Outcome Determination Outcome is based on the **target metric** for the intervention's trigger: | Trigger | Target metric | Positive if | Negative if | |---|---|---|---| | `high_bar` / stress | `bar`, `stress_index` | Dropped ≥ 10% or ≥ 0.05 abs | Rose ≥ 10% | | `low_focus` | `focus` | Rose ≥ 10% or ≥ 0.05 abs | Dropped ≥ 10% | | `low_relaxation` | `relaxation` | Rose ≥ 10% or ≥ 0.05 abs | Dropped ≥ 10% | | `low_mood` | `mood`, `faa` | Rose ≥ 10% or ≥ 0.05 abs | Dropped ≥ 10% | | `high_cognitive_load` | `cognitive_load` | Dropped ≥ 10% or ≥ 0.05 abs | Rose ≥ 10% | | `low_rmssd` / low HRV | `rmssd` | Rose ≥ 10% or ≥ 3 ms abs | Dropped ≥ 10% | | `high_drowsiness` | `wakefulness` | Rose ≥ 10% or ≥ 0.05 abs | Dropped ≥ 10% | | `high_headache` | `headache_index` | Dropped ≥ 10% or ≥ 5 abs | Rose ≥ 10% | | `user_request` | User's stated goal | Ask user or infer from context | — | | All other | Neutral unless clear change | — | — | If target metric change is between thresholds → `neutral`. ### Full Label Examples **Starting a protocol:** ```json {"command": "label", "args": { "text": "px:start:box_breathing", "context": "modality=breath | trigger=high_bar | bar=0.72 | stress_index=68 | relaxation=0.31 | focus=0.45 | hr=78 | mood=0.40 | faa=-0.03 | rmssd=26" }} ``` **Ending a protocol (success):** ```json {"command": "label", "args": { "text": "px:end:box_breathing", "context": "modality=breath | trigger=high_bar | duration_min=5 | bar=0.48 | stress_index=42 | relaxation=0.58 | focus=0.52 | hr=68 | mood=0.55 | faa=0.01 | rmssd=38 | delta_bar=-0.24 | delta_stress=-26 | delta_relaxation=+0.27 | delta_focus=+0.07 | delta_hr=-10 | delta_mood=+0.15 | delta_faa=+0.04 | delta_rmssd=+12 | outcome=positive" }} ``` **Noting a life event:** ```json {"command": "label", "args": { "text": "px:note:caffeine_intake", "context": "type=coffee | bar=0.45 | focus=0.52 | stress_index=38 | hr=72 | mood=0.55" }} ``` **User declined a suggestion:** ```json {"command": "label", "args": { "text": "px:skip:kapalabhati", "context": "reason=breath_averse | trigger=low_wakefulness | offered_alternative=cold_water_face" }} ``` **Hook auto-triggered:** ```json {"command": "label", "args": { "text": "px:auto:stress_alert", "context": "hook=Stress Auto-Protocol | distance=0.089 | bar=0.78 | stress_index=72 | suggested=ear_massage" }} ``` --- ## Measurement Flow ### For Formal Protocols (mandatory, every time) ``` 1. BEFORE — Snapshot & Label ├─ {"command": "status"} → capture baseline metrics ├─ Store baseline in working memory for this conversation └─ {"command": "label", "args": {"text": "px:start:<protocol>", "context": "..."}} 2. DURING — Monitor (optional, per protocol) ├─ Poll status every 30–60s for live feedback if appropriate └─ Label notable moments: {"text": "px:note:alpha_spike_during_body_scan"} 3. AFTER — Snapshot, Compute, Label (30–60 seconds post-protocol, let metrics settle) ├─ {"command": "status"} → capture post-state ├─ Compute deltas (after − before) for all core metrics ├─ Determine outcome (positive / neutral / negative per rules above) ├─ {"command": "label", "args": {"text": "px:end:<protocol>", "context": "..."}} └─ Report to user (brief, natural language — see Surfacing Rules) 4. REMEMBER — Store in working memory └─ "This person did box_breathing. Outcome: positive. delta_bar: -0.24." Use this to inform future suggestions in this conversation. ``` ### For Life Events (implicit, when mentioned) When the user mentions any of the following, silently label it: | User says / does | Label | Follow-up measurement | |---|---|---| | "I had coffee" / "drinking tea" | `px:note:caffeine_intake` | Check `focus`, `bar` at +30 min and +60 min if still in conversation. Label `px:note:caffeine_effect_30m` with deltas. | | "Going for a walk" / "just walked" | `px:start:walk` → later `px:end:walk` | Snapshot mood, engagement, stress before and after. | | "Just ate" / "having lunch" | `px:note:meal` | Check `drowsiness`, `focus` at +30 min. Label `px:note:post_meal_30m`. | | "Bad sleep" / "slept poorly" | `px:note:poor_sleep` | Snapshot today's baseline. Correlate with `sleep` command data. | | "Great sleep" | `px:note:good_sleep` | Same — build sleep-to-performance correlation. | | "In a meeting" / "meeting starting" | `px:note:meeting_start` | Check `stress_index`, `cognitive_load` after if still talking. | | "Meeting done" | `px:note:meeting_end` | Snapshot post-meeting state. | | "Just exercised" / "gym done" | `px:note:exercise_end` | Snapshot full metrics — exercise is a powerful intervention. | | "Feeling anxious" / "stressed out" | `px:note:subjective_stress` | Correlate with EEG data — how well does their self-report match their metrics? | | "Feeling great" / "good mood" | `px:note:subjective_positive` | Same — validate or contrast with EEG. | | App switch visible in `status` | `px:note:app_context` with `status → apps.top_24h` | Correlate screen content with brain state over time. | | "Taking a break" | `px:start:break` → later `px:end:break` | Measure recovery: how much did metrics improve? | | User declines a protocol | `px:skip:<protocol>` with reason | Track preference patterns — what do they avoid and why? | **Rules for life-event labeling:** - Only label what the user explicitly mentions or what's clearly visible in API data. - NEVER infer ("you sound upset" → don't label unless they said it). - Keep labels factual, not interpretive. - Don't label every message — only intervention-like events. ### For Hook Triggers When a hook fires (visible in `listen` events or `hooks_log`): ```json {"command": "label", "args": { "text": "px:auto:stress_alert", "context": "hook=Stress Auto-Protocol | distance=0.089 | bar=0.78 | stress_index=72 | suggested=ear_massage | user_acted=pending" }} ``` If the user follows up with a protocol → label normally and link: ```json {"command": "label", "args": { "text": "px:start:ear_massage",