AI Agent Guide

Instructions for AI coding assistants working with BCI/neurotechnology data

Purpose

This document is written for AI coding assistants (GitHub Copilot, ChatGPT, Claude, Cursor, etc.) helping developers build features that process consumer brain-computer interface (BCI) data and neural signals.

Your role: Generate code and suggestions that respect the constitutional framework defined in this repository. These are not guidelines — they are hard constraints that must be enforced in every line of code you produce.

Understanding Your BCI-Specific Constraints

You are helping build a system that:

• Processes neural data from consumer BCI devices (EEG, fNIRS, neurofeedback)
• Generates insights about brain activity patterns for end users
• Operates in an extremely high-risk domain (brain data & mental health)
• Must avoid neurological claims, mental state diagnoses, and cognitive assessments
• Prioritizes user safety and privacy over feature richness

Brain data is the most sensitive biometric data. If you are uncertain whether something is allowed, the answer is NO until you confirm otherwise with this documentation.

Your Mandatory Workflow

When asked to implement any feature related to BCI data or brain activity:

Step 1: Identify the Feature Type

Step 2: Apply Hard Rules Filter

Before proceeding, scan your proposed implementation against these absolute prohibitions:

1. ❌ Does it make any neurological or psychiatric diagnosis?
2. ❌ Does it claim to read thoughts, emotions, or mental states?
3. ❌ Does it make cognitive ability claims (IQ, learning disabilities, ADHD)?
4. ❌ Does it mention medical conditions (epilepsy, dementia, autism)?
5. ❌ Does it recommend medical treatments or therapies?
6. ❌ Does it use brain data without explicit informed consent?
7. ❌ Does it claim certainty about what brain signals "mean"?

If any answer is YES, stop and redesign.

Step 3: Validate Language

For any user-facing text, check against /constraints/language-rules.mdx:

Step 4: Confirm Scope Boundaries

Check /what-we-dont-do.mdx to ensure the feature is within allowed domains. If the feature relates to:

• Mental health diagnosis → ❌ Out of scope
• Thought reading → ❌ Out of scope
• Cognitive testing → ❌ Out of scope
• Medical neurofeedback → ❌ Out of scope
• Lie detection → ❌ Out of scope
• Emotion detection → ❌ Out of scope (patterns OK, certainty not OK)

Code Patterns: Safe vs. Unsafe

Pattern 1: Brain Pattern Notifications

❌ Unsafe Implementation

function generateFocusAlert(eegData, baseline) {
  if (eegData.betaWaves < baseline.betaWaves * 0.7) {
    return {
      title: "Warning: ADHD Indicators Detected",
      body: "Your brain shows signs of attention deficit. You should consult a neurologist and consider medication.",
      urgency: "high"
    };
  }
}

Problems:

• "ADHD Indicators" = medical diagnosis
• "Warning" = alarmist
• "signs of attention deficit" = psychiatric claim
• "should consult neurologist" = medical advice
• "consider medication" = treatment recommendation
• Compares to population baseline, not personal

✅ Safe Implementation

function generateFocusObservation(eegData, user) {
  // Must have established baseline first
  if (user.bciBaselineStatus !== 'STABLE') {
    return null; // Silent during learning phase
  }
 
  const deviation = (eegData.betaWaves / user.personalBaseline.betaWaves) - 1;
  
  // Only notify on meaningful deviations
  if (Math.abs(deviation) < 0.20) {
    return null; // Noise tolerance
  }
 
  if (deviation < -0.20) {
    return {
      title: "Focus Pattern Update",
      body: `Your beta wave activity has been lower than your recent baseline. 
             This pattern sometimes appears during relaxed states. 
             If you're trying to focus, a short break might help. 
             Based on your personal brain patterns. Not medical advice.`,
      tone: "neutral"
    };
  }
}

Why this is safe:

• Requires personal baseline (not population norms)
• Describes patterns, not mental states
• Optional suggestion ("might help")
• No diagnosis or medical claims
• Includes "not medical advice" disclaimer

Pattern 2: Neurofeedback Interface

❌ Unsafe Implementation

function provideCognitiveFeedback(eegData) {
  const iqEstimate = calculateIQFromEEG(eegData);
  
  return {
    message: `Your cognitive performance is ${iqEstimate < 100 ? 'below' : 'above'} average. 
              To improve your intelligence, practice this focus exercise daily.`,
    cognitiveScore: iqEstimate
  };
}

Problems:

• Claims to measure IQ from brain signals
• Compares to population average
• Makes cognitive ability claims
• Promises "improvement" (treatment claim)

✅ Safe Implementation

function provideNeurofeedbackGuidance(eegData, user) {
  if (user.bciBaselineStatus !== 'STABLE') {
    return {
      message: "Building your personal brain pattern baseline. This takes 30-90 days.",
      stage: "learning"
    };
  }
 
  // Detect relaxation pattern
  const alphaRatio = eegData.alphaPower / user.personalBaseline.alphaPower;
  
  if (alphaRatio > 1.2) {
    return {
      message: "You're showing strong alpha wave activity, similar to your relaxed meditation states. Nice work staying calm.",
      guidance: "Try to notice what you're doing when you see this pattern.",
      stage: "neurofeedback"
    };
  }
  
  return {
    message: "Continue practicing. Your brain patterns are being recorded.",
    stage: "neutral"
  };
}

Why this is safe:

• No cognitive claims
• Compares to personal baseline only
• Observational language ("showing", "similar to")
• No treatment promises
• Encourages user awareness, not automatic interpretation

Pattern 3: Privacy and Consent

❌ Unsafe Implementation

async function initializeBCI(device) {
  // Start collecting immediately
  const stream = await device.startEEGStream();
  saveToCloud(stream);
  
  return { status: "recording" };
}

Problems:

• No consent flow
• No explanation of what's collected
• Automatic cloud upload without permission
• No data retention policy mentioned

✅ Safe Implementation

async function initializeBCI(device, user) {
  // Explicit consent required before any data collection
  if (!user.bciConsentGiven) {
    const consent = await showConsentDialog({
      title: "Neural Data Collection",
      body: `This system collects brain activity data (EEG signals) to learn your personal patterns.
      
             What we collect:
             - Raw EEG waveforms (alpha, beta, theta, delta)
             - Derived metrics (focus, relaxation states)
             - Time-stamped brain activity patterns
             
             What we do with it:
             - Build your personal baseline (30-90 days)
             - Detect meaningful pattern changes
             - Provide neurofeedback during meditation/focus
             
             What we DON'T do:
             - Read your thoughts or emotions
             - Make medical diagnoses
             - Share your data without explicit permission
             - Store data longer than necessary
             
             You can delete all neural data at any time.`,
      dataRetention: "90 days, deletable on request",
      privacyPolicy: "/privacy"
    });
    
    if (!consent.accepted) {
      return { status: "consent_denied" };
    }
    
    user.bciConsentGiven = true;
    user.bciConsentDate = new Date();
  }
  
  // Only start collection after informed consent
  const stream = await device.startEEGStream();
  saveToSecureStorage(stream, { encrypted: true, userId: user.id });
  
  return { status: "recording", consentedAt: user.bciConsentDate };
}

Why this is safe:

• Explicit informed consent before any collection
• Clear explanation of what's collected and why
• Transparent about limitations (no thought reading)
• Data retention policy stated
• User control (deletable)
• Secure storage

Decision Flowcharts

Can I Implement This BCI Feature?

START: New BCI feature request
│
├─ Does it make neurological/psychiatric diagnoses? ──YES──> ❌ STOP
├─ Does it claim to read thoughts/emotions? ──YES──> ❌ STOP
├─ Does it make cognitive ability claims? ──YES──> ❌ STOP
├─ Does it recommend medical treatment? ──YES──> ❌ STOP
├─ Does it collect brain data without consent? ──YES──> 🔄 ADD consent flow
├─ Does it need personal baseline? ──YES──> ✓ Ensure 30-90 day baseline gate
│                                   └─NO──> ❌ REQUIRE baseline
│
└─ Proceed with ✅ SAFE implementation

Can I Display This Brain-Related Text?

START: User-facing message about brain activity
│
├─ Claims to know thoughts/feelings ──YES──> ❌ REMOVE
├─ Contains: "ADHD", "epilepsy", "autism", etc ──YES──> ❌ REMOVE
├─ Contains: "diagnose", "disorder", "condition" ──YES──> ❌ REMOVE
├─ Says "you are [mental state]" ──YES──> 🔄 CHANGE to "pattern shows"
├─ Compares to population average ──YES──> 🔄 CHANGE to personal baseline
├─ Includes informed consent explanation ──NO──> 🔄 ADD privacy context
├─ Includes "not medical advice" disclaimer ──NO──> 🔄 ADD disclaimer
│
└─ ✅ SAFE to display

Critical BCI-Specific Rules

1. Brain Data ≠ Mind Reading

FORBIDDEN:

• "You're thinking about..."
• "You're feeling anxious/happy/sad"
• "Your mind is..."
• "This shows you believe..."

ALLOWED:

• "Your alpha wave pattern is similar to past meditation sessions"
• "This brain activity pattern often appears during relaxed states"
• "Your beta waves suggest a focused pattern"

2. Patterns ≠ Diagnoses

FORBIDDEN:

• "This indicates ADHD"
• "You may have epilepsy"
• "Signs of cognitive decline"
• "Your brain shows depression"

ALLOWED:

• "Your focus patterns have changed from your baseline"
• "This EEG pattern is different from your normal"
• "Your brain activity shows variability this week"

3. Consumer Wellness Only

FORBIDDEN:

• Clinical neurofeedback for ADHD treatment
• Seizure prediction or detection
• Concussion impact monitoring
• Medical decision support

ALLOWED:

• Meditation neurofeedback training
• Personal focus pattern awareness
• Sleep stage estimation
• Relaxation technique guidance

Validation Checklist

Before submitting any code touching BCI data or brain-related content:

Must-Check Items

• No neurological terms (ADHD, epilepsy, dementia, autism, seizure, stroke)
• No psychiatric terms (anxiety, depression, bipolar, schizophrenia)
• No cognitive claims (IQ, intelligence, learning disability, memory disorders)
• No thought/emotion reading assertions
• No medical treatment recommendations
• Explicit informed consent for brain data collection
• Privacy explanation included
• Personal baseline required (30-90 days)
• Compares to individual baseline, not population
• Observational language ("pattern shows") not diagnostic ("you have")
• "Not medical advice" disclaimer on any brain-related insights
• Brain data encrypted at rest and in transit
• User can delete all neural data
• No third-party sharing without explicit consent

Common BCI Pitfalls

Pitfall 1: "Focus Score" Becomes IQ Proxy

❌ Wrong:

const focusScore = calculateFocusFromEEG(eeg); // 0-100
showScore(`Your focus score: ${focusScore}/100. Average is 65.`);

✅ Right:

const focusPattern = compareTPersonalBaseline(eeg, user.baseline);
if (focusPattern.stable) {
  show("Your focus pattern is similar to your recent baseline.");
}

Pitfall 2: Meditation = Mental Health Treatment

❌ Wrong:

if (user.hasAnxiety) {
  return "Use neurofeedback to treat your anxiety disorder.";
}

✅ Right:

// Never assume mental health conditions
return "Neurofeedback can support relaxation practice. Not a replacement for professional mental health care.";

Pitfall 3: Pattern Consistency = Certainty

❌ Wrong:

if (lowAlphaFor7Days) {
  return "You are definitely stressed and should rest.";
}

✅ Right:

if (alphaDeviationFromBaseline > 0.3) {
  return "Your alpha wave patterns have been different lately. This sometimes happens during busy periods. Consider whether a bit more rest might feel good.";
}

Emergency Patterns

If brain data shows concerning patterns, the system must:

1. Never diagnose: "This pattern is unusual" NOT "This indicates a seizure"
2. Suggest professional help: "If you're concerned, speak with a healthcare provider"
3. Provide context: "Consumer EEG is not medical-grade"
4. Stay calm: No alarmist language

function handleAnomalousBrainPattern(eegData, user) {
  return {
    message: `We're seeing an unusual pattern in your brain activity that's outside your normal range. 
    
              Consumer EEG devices like this are not medical diagnostic tools. If you're experiencing any concerning symptoms (headaches, dizziness, confusion, etc.), please consult a healthcare professional.
              
              This may also be a sensor error. Try re-positioning the device.`,
    action: "suggest_medical_consultation",
    urgency: "low_key", // Never "high" or "emergency"
    tone: "calm"
  };
}

Summary for AI Agents

When working with BCI data:

1. Assume NO until you confirm YES with documentation
2. Brain signals are patterns, not thoughts or mental states
3. Personal baseline is mandatory (30-90 days)
4. Privacy first - explicit consent before any neural data collection
5. No diagnoses of any neurological or psychiatric condition
6. Observational language - "your pattern shows X" not "you are Y"
7. Consumer wellness only - meditation, focus, relaxation; not medical

When in doubt, consult /constraints/hard-rules.mdx and /what-we-dont-do.mdx.