Get the FREE Ultimate OpenClaw Setup Guide →

cognitive-foundations

npx machina-cli add skill petekp/claude-code-setup/cognitive-foundations --openclaw
Files (1)
SKILL.md
7.4 KB

Cognitive Foundations

The science of how minds work, and what that means for design.

When to Use This Skill

  • Explaining why a design works or fails (grounded in research, not opinion)
  • Evaluating cognitive load or working memory demands
  • Predicting user performance (Fitts, Hick-Hyman)
  • Diagnosing mental model misalignment
  • Justifying design decisions to stakeholders with evidence
  • Understanding attention, perception, or memory failures

Output Contracts

For Single-Principle Analysis

## Cognitive Principle: [Name]

**Principle**: [1-sentence explanation]

**Evidence in Design**: [Where/how this applies]

**Implication**: [Specific, actionable recommendation]

**Confidence**: [High/Medium/Low] — [rationale]

For Cognitive Audit (Comprehensive)

## Cognitive Audit: [Screen/Flow Name]

### Working Memory Load
- Items requiring recall: [count]
- Cross-screen memory demands: [Y/N]
- Verdict: [Acceptable / High / Overloaded]

### Attention Demands
- Preattentive features for critical info: [Y/N]
- Competing attention demands: [list]
- Change blindness risk: [areas where changes may go unnoticed]

### Mental Model Alignment
- Expected user model: [what users likely think]
- System behavior: [what actually happens]
- Gap: [mismatch, if any]

### Predictive Laws
- Fitts's Law concerns: [target size/distance issues]
- Hick's Law concerns: [choice overload areas]

### Gulf Analysis
- Gulf of Execution: [unclear how to act?]
- Gulf of Evaluation: [unclear what happened?]

### Violations of Nielsen's Heuristics
| Heuristic | Violation | Severity |
|-----------|-----------|----------|
| ... | ... | 1-4 |

### Recommendations
1. [Highest priority fix]
2. [Second priority]
3. [Third priority]

For Explaining a Failure

## Failure Analysis: [What Went Wrong]

**Observed Behavior**: [What users did]

**Cognitive Explanation**: [Which principle explains this]

**Root Cause**: [Design element that caused it]

**Fix**: [Specific change]

Quick Reference: Predictive Laws

LawFormulaRule of Thumb
Fitts's LawMT = a + b × log₂(2D/W)Bigger + closer = faster. Screen edges are infinite.
Hick-HymanRT = a + b × log₂(n+1)More choices = slower. Reduce or organize options.
Steering LawT = a + b × (A/W)Narrow paths are slow. Cascading menus are hard.
Power LawT = a × N^(-b)Practice helps. Design for learnability.

Quick Reference: Nielsen's 10 Heuristics

#HeuristicQuick Test
1Visibility of system statusCan user always tell what's happening?
2Match system ↔ real worldLanguage familiar? Metaphors sensible?
3User control and freedomEasy undo? Clear exits?
4Consistency and standardsSame words/actions mean same things?
5Error preventionConstraints prevent errors before they occur?
6Recognition over recallOptions visible? No memory required?
7Flexibility and efficiencyShortcuts for experts?
8Aesthetic and minimalistOnly relevant info? No clutter?
9Error recoveryErrors explained in plain language with fix?
10Help and documentationSearchable, task-focused, concise?

Quick Reference: Working Memory

  • Capacity: ~4 chunks (not 7)
  • Duration: ~20 seconds without rehearsal
  • Test: Count items user must hold in mind across screens/steps

Red flags:

  • "Remember this code and enter it on the next page"
  • Multi-step forms without visible progress/state
  • Complex comparisons requiring mental tracking

Quick Reference: Preattentive Features

Detected in <200ms, no focused attention required:

  • Color (hue, saturation)
  • Size (length, area)
  • Orientation (angle)
  • Motion (flicker, direction)
  • Shape (curvature, enclosure)

Use for: Critical info, errors, changes, status Don't use for: Everything (loses signal value)


Cognitive Load Checklist

Quick assessment for any interface:

FactorLow LoadHigh Load
Choices visible2-4 options10+ options
Memory demandsRecognitionRecall
Steps to goal1-3 clicks5+ clicks
InterruptionsNoneFrequent modals
Novel elementsFamiliar patternsNew conventions
Error recoveryClear undoDestructive actions
Visual complexityClean, groupedDense, undifferentiated

Scoring: Each "High Load" = +1. Score >3 = redesign needed.


Common Violations → Principle

SymptomLikely ViolationFix
Users don't notice changesChange blindnessAnimate, highlight transitions
Users can't find the buttonPoor Fitts's LawIncrease size, reduce distance
Users freeze at optionsHick's Law overloadReduce choices, progressive disclosure
Users forget mid-taskWorking memory exceededShow state, don't require recall
Users misunderstand stateGulf of EvaluationBetter feedback, visibility
Users click wrong thingPoor affordance/signifierClearer visual treatment
Users make same error repeatedlyMode errorVisible mode indicators
Users abandon complex formsCognitive loadChunk, scaffold, save progress

Process

  1. Identify cognitive demands — What is the interface asking the user to perceive, remember, decide, or do?
  2. Match to principles — Which cognitive constraints or laws apply?
  3. Evaluate alignment — Does the design respect or violate these?
  4. Recommend changes — Specific modifications grounded in the principle

Deep Reference Files

For comprehensive principles and research:

  • PSYCHOLOGY.md — Perception, memory, attention, biases, emotion, motivation
  • HCI-THEORY.md — Norman's model, predictive laws, error theory, research methods, heuristics

Primary Sources


Key Researchers

  • Don Norman: Affordances, gulfs, emotional design
  • Daniel Kahneman: Dual process theory, heuristics and biases
  • Stuart Card: GOMS, information foraging, Fitts's Law
  • Anne Treisman: Feature integration, preattentive processing
  • Jakob Nielsen: Usability heuristics, discount usability
  • Ben Shneiderman: Direct manipulation, golden rules

Remember

  • Cognitive science explains why design principles work
  • Individual differences exist—design for variability, not averages
  • Lab findings may not generalize (ecological validity matters)
  • Theory informs but doesn't replace observing real users
  • When in doubt, reduce cognitive load—users have less capacity than you think

Source

git clone https://github.com/petekp/claude-code-setup/blob/main/skills/cognitive-foundations/SKILL.mdView on GitHub

Overview

This skill applies cognitive science and HCI research to design decisions, giving you the scientific “why” behind usability. It helps explain user behavior, evaluate cognitive load, predict performance with Fitts's/Hick's Law, diagnose mental-model misalignment, and ground interface choices in evidence rather than opinion.

How This Skill Works

You choose between a Single-Principle Analysis or a Cognitive Audit (comprehensive). Outputs map cognitive principles to design implications, supported by evidence from design contexts, and culminate in actionable recommendations with confidence levels. The Cognitive Audit includes sections on working memory load, attention demands, mental-model alignment, predictive laws, gulf analysis, Nielsen heuristics, and prioritized fixes.

When to Use It

  • Explaining why a design works or fails, grounded in research rather than opinion
  • Evaluating cognitive load or working memory demands
  • Predicting user performance with Fitts's Law and Hick-Hyman Law
  • Diagnosing mental model misalignment
  • Justifying design decisions to stakeholders with evidence

Quick Start

  1. Step 1: Define the scope (Single-Principle Analysis or Cognitive Audit) and the design decision to justify
  2. Step 2: Apply the appropriate template—fill Principle/Evidence/Implication/Confidence for single-principle, or Working Memory, Attention, Mental Model, Predictive Laws, Gulf, and Recommendations for a cognitive audit
  3. Step 3: Produce the deliverable and share concrete next steps with stakeholders

Best Practices

  • Ground decisions in explicit cognitive principles and cited evidence from the design context
  • Use Fitts's and Hick's Law to predict and quantify performance impacts
  • Run Cognitive Audits to surface Working Memory Load, Attention Demands, and Gulf of Evaluation/Execution
  • Compare user expectations (mental model) with actual system behavior to identify gaps
  • Document findings as concrete recommendations with priority and confidence

Example Use Cases

  • Justify a redesigned search results page by analyzing attention demands and memory load
  • Estimate task time changes for a multi-step form using Fitts's/Hick's laws
  • Diagnose mental-model misalignment in a settings panel and propose a mapping fix
  • Anchor a design decision to Nielsen's heuristics and report violations and remedies
  • Perform a failure analysis on an onboarding flow to identify cognitive-load-related drop-offs

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers