Imported from fabioc-aloha/alex-cognitive-architecture (.github/skills/cognitive-load/SKILL.md). Install upstream with npx skills add fabioc-aloha/alex-cognitive-architecture --skill cognitive-load. Copyright stays with the author.

Cognitive Load Skill

Don't overwhelm — chunk, scaffold, summarize first.

Core Principle

Working memory holds 4±1 items (Miller's Law). Exceed this → comprehension drops, frustration rises. Every explanation must respect this limit.

Cognitive Load Types

Key insight: We can't reduce intrinsic load, but we can minimize extraneous and maximize germane.

Chunking Strategies

The 3-5 Rule

Break any complex response into 3-5 logical chunks. Each chunk should be digestible in isolation.

## Bad: Wall of text
Here's everything you need to know about authentication including JWTs 
and sessions and OAuth and SAML and how to implement login and logout 
and password reset and MFA and token refresh and...

## Good: Chunked
### 1. Authentication Basics
Brief explanation of what authentication is.

### 2. Token-Based (JWT)
Just the JWT pattern.

### 3. Session-Based
Just the session pattern.

### 4. When to Use Which
Comparison table.

Group Related Items

Present related concepts together, separated from unrelated ones.

## Good structure
### Input Validation
- Check required fields
- Validate formats
- Sanitize user input

### Database Operations
- Connect to DB
- Execute query
- Handle results

## Bad: Mixed concerns
- Check required fields
- Connect to DB
- Validate formats
- Execute query (why is this here?)

Progressive Disclosure

Level 1: Summary (everyone gets this) Level 2: Details (for those who want more) Level 3: Implementation (only when requested)

## Level 1: Summary
OAuth is a protocol that lets users grant third-party apps access 
to their data without sharing passwords.

## Level 2: Details (expand if asked)
OAuth 2.0 defines four roles: Resource Owner, Client, Authorization 
Server, and Resource Server. The flow involves redirecting the user 
to authorize, then exchanging an authorization code for tokens.

## Level 3: Implementation (only if specifically requested)
[Full code example with error handling, token storage, refresh logic]

Always ask before going deeper: "Want me to dive into the implementation details?"

Summarize First Pattern

Start EVERY complex explanation with a summary. Then optionally expand.

## Summary
Authentication verifies who you are. Authorization determines what you 
can access. JWT is a stateless token format. Sessions are server-stored.

## Details
[Only if user wants more]

High Load vs Low Load Presentation

Code Example: High vs Low Load

// HIGH LOAD: Too much at once
function processUserRegistration(data) {
  if (data.email && data.email.includes('@') && data.email.length > 5) {
    if (data.password && data.password.length >= 8 && /[A-Z]/.test(data.password) && /[0-9]/.test(data.password)) {
      if (data.age && data.age >= 18) {
        // 3 levels deep, reader lost context
      }
    }
  }
}

// LOW LOAD: Guard clauses, flat structure
function processUserRegistration(data) {
  if (!isValidEmail(data.email)) {
    return { error: 'Invalid email' };
  }
  
  if (!isStrongPassword(data.password)) {
    return { error: 'Password too weak' };
  }
  
  if (!isAdult(data.age)) {
    return { error: 'Must be 18+' };
  }
  
  return createUser(data);
}

Overload Signals and Responses

3-3-3 Rule

A quick heuristic for any explanation:

• 3 sentences for the summary
• 3 examples to make it concrete
• 3 minutes before checking understanding

If the user hasn't responded after a complex explanation, pause and check in rather than continuing to add load.

Scaffolding Complex Topics

For high-intrinsic-load topics, build up gradually:

### Step 1: Analogy to familiar concept
"A database index is like a book's index — it lets you find 
content without reading every page."

### Step 2: Simple example
"SELECT * FROM users WHERE email = 'x' — without index, 
scans all rows. With index, jumps directly."

### Step 3: The real complexity
"B-tree indexes balance lookup speed vs. write overhead..."

Self-Check Before Responding

Before sending a complex response, ask:

1. Did I summarize first?
2. Is it chunked into 3-5 sections?
3. Am I introducing only ONE new concept per section?
4. Can I replace jargon with plain language?
5. Would an example make this clearer?

If any answer is "no", revise before sending.