cbrowser 16.7.0 → 16.7.2

package/docs/traits/Trait-InterruptRecovery.md

@@ -0,0 +1,241 @@
+# Interrupt Recovery
+
+**Category**: Tier 2 - Emotional Traits
+**Scale**: 0.0 (poor recovery) to 1.0 (excellent recovery)
+
+## Definition
+
+Interrupt recovery measures a user's ability to resume tasks after interruptions, distractions, or context switches. This trait determines whether users can pick up where they left off after phone calls, notifications, browser tab switches, or system timeouts. Users with low interrupt recovery lose their mental context and must restart tasks from the beginning, often with degraded performance. Users with high interrupt recovery leverage environmental cues (breadcrumbs, form progress indicators, browser history) to seamlessly continue their work with minimal lost progress.
+
+## Research Foundation
+
+### Primary Citation
+> "We found that the average time to return to a disrupted task was 23 minutes 15 seconds. Furthermore, people did not simply resume the interrupted task; rather, they engaged in an average of 2.26 intervening activities before returning to the original task."
+> -- Mark, G., Gonzalez, V.M., & Harris, J., 2005, p. 112
+
+**Full Citation (APA 7):**
+Mark, G., Gonzalez, V. M., & Harris, J. (2005). No task left behind? Examining the nature of fragmented work. *Proceedings of the SIGCHI Conference on Human Factors in Computing Systems*, 321-330.
+
+**DOI**: https://doi.org/10.1145/1054972.1055017
+
+### Supporting Research
+
+> "Resumption lag - the time to resume a task after an interruption - is significantly affected by the complexity of the primary task and the length of the interruption. Longer interruptions result in greater context loss and longer resumption times."
+> -- Altmann, E.M., & Trafton, J.G., 2002, p. 41
+
+**Full Citation (APA 7):**
+Altmann, E. M., & Trafton, J. G. (2002). Memory for goals: An activation-based model. *Cognitive Science*, 26(1), 39-83.
+
+**DOI**: https://doi.org/10.1207/s15516709cog2601_2
+
+### Key Numerical Values
+
+| Metric | Value | Source |
+|--------|-------|--------|
+| Average task resumption time | 23 min 15 sec | Mark et al. (2005) |
+| Intervening activities before resumption | 2.26 average | Mark et al. (2005) |
+| Resumption lag (controlled lab) | 2-30 seconds | Altmann & Trafton (2002) |
+| Error rate increase post-interruption | 2x baseline | Monk et al. (2008) |
+| Context decay half-life | 15-60 seconds | Altmann & Trafton (2002) |
+| Visual cue resumption benefit | 40-60% faster recovery | Trafton et al. (2011) |
+
+### Interruption Types
+
+| Type | Description | Typical Duration |
+|------|-------------|------------------|
+| `external` | Phone call, person, notification | Seconds to hours |
+| `system` | Timeout, crash, page refresh | Instant to minutes |
+| `self_initiated` | Tab switch, new thought, distraction | Seconds to minutes |
+| `timeout` | Session expiration, idle disconnect | Instant |
+
+## Behavioral Levels
+
+| Value | Label | Behaviors |
+|-------|-------|-----------|
+| 0.0-0.2 | Very Poor | Loses all context after any interruption; must restart forms from beginning; forgets goal of task after distraction; cannot recall previous steps; re-reads entire page after tab switch; session timeout causes complete task abandonment; no use of environmental cues for recovery; takes full 23+ minutes to resume complex tasks |
+| 0.2-0.4 | Poor | Loses 40-60% of progress after interruption; struggles to remember where they were; re-enters data they previously completed; skips steps when resuming; high error rate post-interruption; may recognize environmental cues but doesn't effectively use them; resumes in wrong section of multi-step process |
+| 0.4-0.6 | Moderate | Loses 10-30% of progress after interruption; can use breadcrumbs and progress indicators to orient; may need to review recent steps; moderate resumption lag (5-15 seconds); error rate slightly elevated after interruption; benefits from "you were here" indicators |
+| 0.6-0.8 | Good | Minimal progress loss (< 10%) after interruption; quickly orients using page state, URL, form values; short resumption lag (2-5 seconds); actively seeks environmental cues; maintains mental context through moderate interruptions; can context-switch between tabs effectively |
+| 0.8-1.0 | Excellent | Near-seamless recovery from interruptions; leverages all environmental cues (breadcrumbs, history, form state); < 2 second resumption lag; mental context persists through long interruptions; can resume days later using browser history; proactively creates own resumption cues (bookmarks, notes) |
+
+## Trait Implementation in CBrowser
+
+### Context Loss Model
+
+CBrowser models context decay using exponential decay modified by trait:
+
+```typescript
+interface InterruptRecoveryState {
+  currentTaskContext: TaskContext;
+  environmentalCues: string[];      // Page elements aiding recovery
+  interruptionLog: Interruption[];  // History of interruptions
+  contextStrength: number;          // 0-1 memory of task context
+}
+
+interface Interruption {
+  type: 'external' | 'system' | 'self_initiated' | 'timeout';
+  duration: number;  // milliseconds
+  timestamp: Date;
+}
+
+// Context decay during interruption
+function calculateContextLoss(
+  interruptRecovery: number,
+  interruptionDuration: number,
+  cuesAvailable: number
+): number {
+  const halfLife = 15000 + (interruptRecovery * 45000);  // 15-60 sec half-life
+  const decayRate = Math.LN2 / halfLife;
+  const baseLoss = 1 - Math.exp(-decayRate * interruptionDuration);
+
+  // Environmental cues reduce loss
+  const cueRecovery = Math.min(0.6, cuesAvailable * 0.1);
+
+  return Math.max(0, baseLoss - cueRecovery);
+}
+```
+
+### Resumption Lag
+
+```typescript
+// Time to resume after interruption
+function getResumptionLag(
+  interruptRecovery: number,
+  contextLoss: number,
+  taskComplexity: number
+): number {
+  const baseLag = 2000;  // 2 seconds minimum
+  const complexityMultiplier = 1 + (taskComplexity * 2);  // 1x to 3x
+  const recoveryFactor = 1 + ((1 - interruptRecovery) * 10);  // 1x to 11x
+  const contextFactor = 1 + (contextLoss * 5);  // 1x to 6x
+
+  return baseLag * complexityMultiplier * recoveryFactor * contextFactor;
+  // Range: 2 seconds to several minutes
+}
+```
+
+### Environmental Cue Detection
+
+```typescript
+// Cues that help users recover context
+const environmentalCues = {
+  breadcrumbs: 0.15,        // "Home > Products > Category"
+  progressIndicator: 0.20,  // "Step 2 of 4"
+  formValues: 0.15,         // Previously entered data visible
+  pageTitle: 0.10,          // Descriptive title
+  recentHistory: 0.15,      // Browser back button history
+  urlPath: 0.10,            // Meaningful URL structure
+  visualPosition: 0.08,     // Scroll position preserved
+  notifications: 0.07       // "You have unsaved changes"
+};
+
+function calculateCueStrength(page: Page): number {
+  return Object.entries(environmentalCues)
+    .filter(([cue]) => page.hasCue(cue))
+    .reduce((sum, [, value]) => sum + value, 0);
+}
+```
+
+### Behavior Post-Interruption
+
+```typescript
+// How user behaves when resuming
+function getResumptionBehavior(
+  interruptRecovery: number,
+  contextLoss: number
+): 'continue' | 'review' | 'restart' {
+  const effectiveRecovery = interruptRecovery * (1 - contextLoss);
+
+  if (effectiveRecovery > 0.6) return 'continue';  // Pick up where left off
+  if (effectiveRecovery > 0.3) return 'review';    // Review recent steps, then continue
+  return 'restart';  // Begin task from start
+}
+```
+
+## Trait Correlations
+
+Research and theoretical models indicate the following correlations:
+
+| Related Trait | Correlation | Research Basis |
+|--------------|-------------|----------------|
+| Working Memory | r = 0.55 | Context maintenance is memory-dependent |
+| Comprehension | r = 0.38 | Understanding structure aids reorientation |
+| Persistence | r = 0.32 | Persistent users try harder to resume |
+| Patience | r = 0.28 | Recovery takes time; patient users invest it |
+| Reading Tendency | r = 0.25 | Readers use text cues for recovery |
+
+### Interaction Effects
+
+- **Interrupt Recovery x Working Memory**: Combined high values create maximally context-resilient users
+- **Interrupt Recovery x Low Patience**: Users may have recovery ability but not time patience to use it
+- **Interrupt Recovery x Comprehension**: High recovery + low comprehension = can find their place but may not understand current step
+
+## Persona Values
+
+| Persona | Interrupt Recovery Value | Rationale |
+|---------|--------------------------|-----------|
+| power-user | 0.75 | Skilled at context-switching; uses environmental cues effectively |
+| first-timer | 0.35 | Lacks schema for interpreting recovery cues |
+| elderly-user | 0.40 | Working memory challenges impede context retention |
+| impatient-user | 0.45 | May have ability but doesn't invest effort to recover |
+| mobile-user | 0.50 | Moderate; mobile users frequently interrupted |
+| screen-reader-user | 0.55 | Developed coping strategies for non-visual navigation |
+| anxious-user | 0.35 | Anxiety impairs working memory and recovery |
+| multi-tasker | 0.70 | Practiced at context-switching |
+
+## UX Design Implications
+
+### For Low Interrupt Recovery Users (< 0.4)
+
+1. **Auto-save everything**: Persist form data frequently and automatically
+2. **Session persistence**: Don't timeout sessions aggressively
+3. **"Welcome back" states**: Detect returning users and restore context
+4. **Prominent progress indicators**: Make "where you are" unmissable
+5. **Breadcrumb navigation**: Clear path back to current location
+6. **Unsaved changes warnings**: Prevent accidental navigation away
+7. **Email/save progress links**: Allow explicit progress saving
+
+### For High Interrupt Recovery Users (> 0.7)
+
+1. **Minimal recovery friction**: Don't force re-authentication unnecessarily
+2. **Smart defaults**: Pre-fill likely values based on previous session
+3. **Quick resume options**: "Continue where you left off" buttons
+4. **Tab state preservation**: Maintain state across browser sessions
+5. **History navigation**: Support effective use of back button
+
+### Environmental Cue Best Practices
+
+| Cue Type | Implementation | Recovery Benefit |
+|----------|----------------|------------------|
+| Progress indicators | Step X of Y, progress bars | 20% faster recovery |
+| Breadcrumbs | Clickable path hierarchy | 15% faster recovery |
+| Form persistence | Save partial form data | 40-60% less re-entry |
+| Descriptive titles | Page-specific, goal-oriented | 10% faster orientation |
+| Scroll restoration | Return to scroll position | Immediate context recovery |
+| Visual state | Expand/collapse states preserved | Reduces re-navigation |
+
+## See Also
+
+- [Trait-WorkingMemory](Trait-WorkingMemory) - Memory capacity (strongly related)
+- [Trait-Resilience](Trait-Resilience) - Emotional recovery from setbacks (different type of recovery)
+- [Trait-Patience](Trait-Patience) - Time tolerance for recovery process
+- [Trait-Persistence](Trait-Persistence) - Motivation to resume rather than abandon
+- [Trait-Index](Trait-Index) - Complete trait listing
+
+## Bibliography
+
+Adamczyk, P. D., & Bailey, B. P. (2004). If not now, when? The effects of interruption at different moments within task execution. *Proceedings of the SIGCHI Conference on Human Factors in Computing Systems*, 271-278. https://doi.org/10.1145/985692.985727
+
+Altmann, E. M., & Trafton, J. G. (2002). Memory for goals: An activation-based model. *Cognitive Science*, 26(1), 39-83. https://doi.org/10.1207/s15516709cog2601_2
+
+Czerwinski, M., Horvitz, E., & Wilhite, S. (2004). A diary study of task switching and interruptions. *Proceedings of the SIGCHI Conference on Human Factors in Computing Systems*, 175-182. https://doi.org/10.1145/985692.985715
+
+Iqbal, S. T., & Horvitz, E. (2007). Disruption and recovery of computing tasks: Field study, analysis, and directions. *Proceedings of the SIGCHI Conference on Human Factors in Computing Systems*, 677-686. https://doi.org/10.1145/1240624.1240730
+
+Mark, G., Gonzalez, V. M., & Harris, J. (2005). No task left behind? Examining the nature of fragmented work. *Proceedings of the SIGCHI Conference on Human Factors in Computing Systems*, 321-330. https://doi.org/10.1145/1054972.1055017
+
+Mark, G., Gudith, D., & Klocke, U. (2008). The cost of interrupted work: More speed and stress. *Proceedings of the SIGCHI Conference on Human Factors in Computing Systems*, 107-110. https://doi.org/10.1145/1357054.1357072
+
+Monk, C. A., Trafton, J. G., & Boehm-Davis, D. A. (2008). The effect of interruption duration and demand on resuming suspended goals. *Journal of Experimental Psychology: Applied*, 14(4), 299-313. https://doi.org/10.1037/a0014402
+
+Trafton, J. G., Altmann, E. M., & Ratwani, R. M. (2011). A memory for goals model of sequence errors. *Cognitive Systems Research*, 12(2), 134-143. https://doi.org/10.1016/j.cogsys.2010.07.010

package/docs/traits/Trait-MentalModelRigidity.md

@@ -0,0 +1,220 @@
+# Mental Model Rigidity
+
+**Category**: Tier 5 - Perception Traits
+**Scale**: 0.0 (highly flexible) to 1.0 (highly rigid)
+
+## Definition
+
+Mental Model Rigidity describes the degree to which users resist updating their internal representations of how systems work when confronted with contradictory evidence. In web and UI contexts, this trait determines how quickly users adapt to interface changes, redesigns, or unexpected behaviors. Users with high mental model rigidity persist in applying outdated interaction patterns, require multiple disconfirming experiences before adjusting their approach, and experience significant frustration when interfaces deviate from their expectations. Users with low rigidity rapidly incorporate new information and adapt their behavior to match current system states.
+
+## Research Foundation
+
+### Primary Citation
+
+> "Mental models are working models that are constructed from knowledge, perception, and inference. People reason by mentally manipulating these models to simulate possible states of affairs. The more deeply entrenched a model, the more evidence is required to revise or abandon it."
+> — Johnson-Laird, P. N., 1983, p. 397
+
+**Full Citation (APA 7):**
+Johnson-Laird, P. N. (1983). *Mental models: Towards a cognitive science of language, inference, and consciousness*. Harvard University Press.
+
+**ISBN**: 978-0674568815
+
+### Supporting Research
+
+> "Users who have developed strong expectations about interface behavior require an average of 3-5 disconfirming experiences before updating their mental model of how the system operates."
+> — Carroll, J. M., & Rosson, M. B., 1987, p. 86
+
+**Full Citation (APA 7):**
+Carroll, J. M., & Rosson, M. B. (1987). Paradox of the active user. In J. M. Carroll (Ed.), *Interfacing thought: Cognitive aspects of human-computer interaction* (pp. 80-111). MIT Press.
+
+**ISBN**: 978-0262530637
+
+### Key Numerical Values
+
+| Metric | Value | Source |
+|--------|-------|--------|
+| Disconfirmations needed to update model | 3-5 experiences | Carroll & Rosson (1987) |
+| Mental model formation time | 2-4 interactions | Norman (1983) |
+| Relearning cost after redesign | 40-60% productivity loss initially | Nielsen (2010) |
+| Interface change adaptation period | 1-3 weeks for major changes | Sears & Jacko (2007) |
+| Error rate post-redesign | 300-400% increase initially | Tognazzini (2003) |
+| Working memory chunks for model | 3-4 active elements | Johnson-Laird (1983) |
+| Model revision resistance | 65% persist despite single failure | Rouse & Morris (1986) |
+
+## Behavioral Levels
+
+| Value | Label | Behaviors |
+|-------|-------|-----------|
+| 0.0-0.2 | Very Flexible | Immediately adapts to interface changes; updates expectations after single disconfirming event; explores new features without prior assumptions; recovers quickly from errors by trying alternative approaches; embraces redesigns without complaint; treats each interaction as learning opportunity |
+| 0.2-0.4 | Flexible | Adapts to changes within 2-3 disconfirming experiences; initially tries familiar patterns but quickly pivots; shows mild surprise at interface changes but adjusts; willing to read help content for new features; accepts redesigns after brief acclimation period; experiments with different approaches when blocked |
+| 0.4-0.6 | Moderate | Requires 3-4 disconfirming experiences to update model; shows visible frustration when familiar patterns fail; attempts old methods repeatedly before adapting; may vocalize "this used to work"; moderate resistance to redesigns; eventually adapts but with notable effort and time |
+| 0.6-0.8 | Rigid | Persists with outdated patterns through 5-6 failures; expresses strong frustration with interface changes; repeatedly clicks where buttons "should be" based on prior experience; blames system for not working "correctly"; strong resistance to redesigns; may seek workarounds to maintain old patterns; frequently requests "old version" |
+| 0.8-1.0 | Very Rigid | Requires 7+ disconfirming experiences before considering model update; intense frustration and potential abandonment when patterns fail; refuses to acknowledge interface has changed; persistent muscle-memory errors; may avoid features that have been redesigned; seeks external help rather than exploring; considers any change "broken"; may switch to competitor products to maintain familiar patterns |
+
+## Web/UI Manifestations
+
+### Common Scenarios Where Mental Model Rigidity Affects Users
+
+**Navigation Redesigns**
+- User clicks where navigation menu used to be after site redesign
+- Expects dropdown behavior but encounters mega-menu
+- Seeks hamburger menu on desktop after mobile experience
+- Looks for footer links in header after site reorganization
+
+**Form Interaction Patterns**
+- Expects Tab key to advance fields but interface uses Enter
+- Assumes clicking submit saves draft (prior experience) but it doesn't
+- Expects date picker but encounters free-form text field
+- Assumes asterisk means optional (prior app) when it means required
+
+**E-commerce Flows**
+- Expects "Add to Cart" in product image area after pattern change
+- Looks for cart icon in top-right after redesign moved it left
+- Assumes checkout is multi-page when now single-page
+- Expects shipping address before payment (old flow was reversed)
+
+**Modal and Dialog Patterns**
+- Clicks outside modal expecting dismissal when it requires button click
+- Expects "X" in top-right when close button is bottom-left
+- Assumes Escape key closes modal when it doesn't
+- Expects confirmation on dialog but action is immediate
+
+**Search Behavior**
+- Uses search syntax from prior interface that doesn't work here
+- Expects autocomplete but interface requires explicit submit
+- Assumes search scope is entire site when it's section-specific
+- Expects results page but gets inline dropdown suggestions
+
+**Authentication Patterns**
+- Enters username then password, but interface asks email first
+- Expects "Remember me" checkbox that doesn't exist
+- Looks for social login options in different position
+- Assumes password visible toggle is checkbox when it's icon
+
+## Trait Correlations
+
+| Related Trait | Correlation | Mechanism |
+|---------------|-------------|-----------|
+| Transfer Learning | r = -0.55 | High transfer learning enables rapid model updates |
+| Procedural Fluency | r = 0.42 | Automated procedures increase rigidity |
+| Patience | r = -0.35 | Impatient users less willing to persist through model updates |
+| Persistence | r = 0.38 | Highly persistent users may over-persist with wrong model |
+| Self-Efficacy | r = -0.28 | Low self-efficacy increases defensive rigidity |
+| Curiosity | r = -0.45 | Curious users more willing to explore new patterns |
+
+## The Model Update Process
+
+### Stages of Mental Model Revision
+
+1. **Initial Failure**: Expected action produces unexpected result
+2. **Retry Phase**: User attempts same action with minor variations
+3. **Frustration Point**: After 2-3 failures, emotional response emerges
+4. **Exploration Phase**: Begins trying alternative approaches
+5. **Insight Moment**: Discovers correct pattern
+6. **Integration**: New pattern begins overwriting old model
+7. **Consolidation**: 5-10 successful repetitions cement new model
+
+### Factors Affecting Update Speed
+
+| Factor | Effect on Rigidity |
+|--------|-------------------|
+| Prior experience depth | More experience = more rigid |
+| Time since last use | Longer gap = more flexible |
+| Emotional investment | Higher investment = more rigid |
+| Similarity to old pattern | More similar = harder to distinguish |
+| Explicit instruction | Direct teaching accelerates update |
+| Multiple simultaneous changes | Increases update difficulty |
+
+## Design Implications
+
+### For High Mental Model Rigidity Users
+
+- Provide transitional interfaces during redesigns
+- Implement "bridge" patterns that honor old and new behaviors
+- Add prominent "What's New" tours for redesigns
+- Maintain familiar anchor points in new designs
+- Use animation to show where elements moved
+- Provide search for features ("Where is Cart?")
+- Allow "classic mode" during transition periods
+- Use progressive disclosure for major changes
+- Add inline hints for changed behaviors
+- Implement ghost images showing old element locations
+
+### For Low Mental Model Rigidity Users
+
+- Can deploy redesigns with minimal onboarding
+- Brief changelog notifications sufficient
+- Will discover changes through exploration
+- Requires less hand-holding during transitions
+
+## Persona Values
+
+| Persona | Value | Rationale |
+|---------|-------|-----------|
+| Rushing Rachel | 0.55 | Time pressure discourages exploration, increases reliance on habits |
+| Careful Carlos | 0.65 | Methodical patterns become entrenched through repeated verification |
+| Distracted Dave | 0.45 | Distractibility prevents deep model formation, enabling flexibility |
+| Senior Sam | 0.80 | Long experience creates deeply entrenched expectations |
+| Focused Fiona | 0.50 | Deep task focus creates strong models but allows analytical updates |
+| Anxious Annie | 0.70 | Anxiety drives preference for predictable, familiar patterns |
+| Mobile Mike | 0.40 | Diverse app experiences create flexible cross-platform expectations |
+| Power User Pete | 0.60 | Expert patterns are efficient but resistant to change |
+| First-Time Freddie | 0.20 | No prior experience means no rigid expectations |
+
+## Measurement Approaches
+
+### Experimental Paradigms
+
+1. **Interface modification studies**: Measure errors after interface change
+2. **Transfer tasks**: Test performance on new version of familiar system
+3. **Think-aloud protocols**: Capture explicit expectations during exploration
+4. **Error recovery analysis**: Time and attempts to recover from model mismatch
+
+### Web-Specific Metrics
+
+- Click heatmap comparison before/after redesign
+- Error rate spike duration after changes
+- Time to first successful task completion post-change
+- Support ticket volume after interface updates
+- A/B test showing new vs. maintained patterns
+
+## Interaction with Change Blindness
+
+Mental Model Rigidity and [Change Blindness](Trait-ChangeBlindness) interact in complex ways:
+
+| Scenario | High Rigidity + High Blindness | High Rigidity + Low Blindness |
+|----------|-------------------------------|------------------------------|
+| UI Redesign | May not notice changes AND struggle when discovered | Notices changes immediately, resists adapting |
+| Error states | Misses error AND repeats same action | Notices error but persists with failed approach |
+| New features | Overlooks new options AND wouldn't use them | Sees new features but avoids them |
+
+## See Also
+
+- [Change Blindness](Trait-ChangeBlindness) - Related perceptual limitation
+- [Transfer Learning](Trait-TransferLearning) - Ability to apply knowledge across contexts
+- [Procedural Fluency](Trait-ProceduralFluency) - Automated interaction patterns
+- [Persistence](Trait-Persistence) - Continuing despite obstacles
+- [Trait Index](Trait-Index) - Complete trait listing
+- [Senior Sam](../personas/Persona-SeniorSam) - High rigidity persona
+
+## Bibliography
+
+Carroll, J. M., & Rosson, M. B. (1987). Paradox of the active user. In J. M. Carroll (Ed.), *Interfacing thought: Cognitive aspects of human-computer interaction* (pp. 80-111). MIT Press.
+
+Gentner, D., & Stevens, A. L. (Eds.). (1983). *Mental models*. Lawrence Erlbaum Associates.
+
+Johnson-Laird, P. N. (1983). *Mental models: Towards a cognitive science of language, inference, and consciousness*. Harvard University Press.
+
+Nielsen, J. (2010). Website response times. *Nielsen Norman Group*. https://www.nngroup.com/articles/website-response-times/
+
+Norman, D. A. (1983). Some observations on mental models. In D. Gentner & A. L. Stevens (Eds.), *Mental models* (pp. 7-14). Lawrence Erlbaum Associates.
+
+Norman, D. A. (2013). *The design of everyday things* (Revised and expanded ed.). Basic Books.
+
+Rouse, W. B., & Morris, N. M. (1986). On looking into the black box: Prospects and limits in the search for mental models. *Psychological Bulletin*, 100(3), 349-363. https://doi.org/10.1037/0033-2909.100.3.349
+
+Sears, A., & Jacko, J. A. (Eds.). (2007). *The human-computer interaction handbook: Fundamentals, evolving technologies and emerging applications* (2nd ed.). CRC Press.
+
+Tognazzini, B. (2003). First principles of interaction design. *AskTog*. https://asktog.com/atc/principles-of-interaction-design/
+
+Young, R. M. (1983). Surrogates and mappings: Two kinds of conceptual models for interactive devices. In D. Gentner & A. L. Stevens (Eds.), *Mental models* (pp. 35-52). Lawrence Erlbaum Associates.

package/docs/traits/Trait-MetacognitivePlanning.md

@@ -0,0 +1,156 @@
+# Metacognitive Planning
+
+**Category**: Tier 4 - Planning Traits
+**Scale**: 0.0 (low) to 1.0 (high)
+
+## Definition
+
+Metacognitive Planning measures a user's ability to think about their own thinking processes, monitor their progress toward goals, and strategically adjust their approach when encountering obstacles. Users with high metacognitive planning actively set sub-goals, predict potential difficulties, evaluate their understanding, and modify their strategies based on ongoing self-assessment. In web interfaces, this manifests as users who pause to consider "What am I trying to accomplish?", "Is this approach working?", and "What should I try next?" Low metacognitive planners tend to react to interfaces without systematic strategy, often clicking impulsively without considering whether their current approach is effective.
+
+## Research Foundation
+
+### Primary Citation
+
+> "Metacognition refers to one's knowledge concerning one's own cognitive processes and products or anything related to them... Metacognition refers, among other things, to the active monitoring and consequent regulation and orchestration of these processes in relation to the cognitive objects or data on which they bear, usually in the service of some concrete goal or objective."
+> -- Flavell, 1979, p. 906
+
+**Full Citation (APA 7):**
+Flavell, J. H. (1979). Metacognition and cognitive monitoring: A new area of cognitive-developmental inquiry. *American Psychologist*, 34(10), 906-911.
+
+**DOI**: https://doi.org/10.1037/0003-066X.34.10.906
+
+### Supporting Research
+
+> "Metacognitive monitoring accuracy varies widely, with estimates ranging from 50% to 90% accuracy depending on task domain and individual differences."
+> -- Dunlosky & Metcalfe, 2009
+
+**Full Citation (APA 7):**
+Dunlosky, J., & Metcalfe, J. (2009). *Metacognition*. SAGE Publications.
+
+### Key Numerical Values
+
+| Metric | Value | Source |
+|--------|-------|--------|
+| Monitoring accuracy range | 50-90% | Dunlosky & Metcalfe (2009) |
+| Planning time overhead | 15-30% of task time | Nelson & Narens (1990) |
+| Error detection rate (high metacog) | 78% | Veenman et al. (2006) |
+| Error detection rate (low metacog) | 34% | Veenman et al. (2006) |
+| Strategy switch threshold | 3-5 failed attempts | Winne & Hadwin (1998) |
+| Goal monitoring frequency | Every 30-60 seconds | Azevedo & Cromley (2004) |
+
+## Behavioral Levels
+
+| Value | Label | Behaviors |
+|-------|-------|-----------|
+| 0.0-0.2 | Very Low | Clicks without strategy; does not recognize when lost; repeats failed actions 5+ times; never pauses to assess progress; blames interface rather than adjusting approach; cannot articulate what they are trying to do; abandons without trying alternatives |
+| 0.2-0.4 | Low | Minimal self-monitoring; recognizes being stuck only after 4+ failed attempts; rarely forms explicit sub-goals; limited awareness of confusion; may eventually try a different approach but without clear reasoning; difficulty remembering what has already been tried |
+| 0.4-0.6 | Moderate | Sets basic goals before starting; monitors progress intermittently; recognizes being stuck after 2-3 failed attempts; can articulate current objective when asked; considers 1-2 alternative approaches; occasionally backtracks strategically; uses browser back button appropriately |
+| 0.6-0.8 | High | Plans approach before clicking; sets explicit sub-goals; monitors progress every 30-60 seconds; recognizes confusion quickly (1-2 attempts); maintains mental model of site structure; strategically explores navigation; remembers and avoids previously failed paths; uses landmarks for orientation |
+| 0.8-1.0 | Very High | Systematic pre-planning with explicit sub-goals; continuous self-monitoring; immediately recognizes when approach is not working; maintains detailed mental map of explored areas; strategic use of browser history, tabs, and search; articulates reasoning aloud or internally; actively predicts outcomes before clicking; efficient backtracking and path correction |
+
+## Web/UI Behavioral Patterns
+
+### Navigation Strategy
+
+| Level | Observed Behavior |
+|-------|-------------------|
+| Very Low | Random clicking; no clear path; returns to homepage repeatedly without learning |
+| Low | Trial-and-error with limited memory; may try same wrong path twice |
+| Moderate | Follows logical paths; uses breadcrumbs when available |
+| High | Scans navigation structure first; forms mental map before deep navigation |
+| Very High | Uses site map, search strategically; opens multiple tabs for comparison |
+
+### Form Completion
+
+| Level | Observed Behavior |
+|-------|-------------------|
+| Very Low | Fills fields randomly; submits without reviewing; surprised by errors |
+| Low | Sequential filling; minimal preview; errors discovered one at a time |
+| Moderate | Reads form overview first; groups related fields; reviews before submit |
+| High | Plans required information before starting; has documents ready |
+| Very High | Pre-reads all fields; prepares all information; validates progressively |
+
+### Error Recovery
+
+| Level | Observed Behavior |
+|-------|-------------------|
+| Very Low | Clicks same broken button repeatedly; does not read error messages |
+| Low | Eventually tries different button; error messages partially read |
+| Moderate | Reads error message; tries suggested fix; seeks help if fix fails |
+| High | Diagnoses error cause; tries multiple systematic solutions |
+| Very High | Prevents errors through preview; when errors occur, uses systematic debugging |
+
+## Trait Correlations
+
+| Related Trait | Correlation | Research Basis |
+|---------------|-------------|----------------|
+| [Working Memory](Trait-WorkingMemory) | r = 0.58 | Metacognitive monitoring requires maintaining current state and goals in working memory (Veenman et al., 2006) |
+| [Persistence](Trait-Persistence) | r = 0.42 | High metacognition enables more effective persistence through strategic adjustment rather than mere repetition (Schraw & Dennison, 1994) |
+| [Comprehension](Trait-Comprehension) | r = 0.51 | Metacognitive awareness improves comprehension monitoring and repair (Flavell, 1979) |
+| [Self-Efficacy](Trait-SelfEfficacy) | r = 0.47 | Self-awareness of capabilities relates to self-efficacy beliefs (Bandura, 1986) |
+| [Satisficing](Trait-Satisficing) | r = -0.35 | High metacognition tends toward maximizing through deliberate evaluation (Simon, 1956) |
+
+## Persona Values
+
+| Persona | Value | Rationale |
+|---------|-------|-----------|
+| power-user | 0.85 | Experts develop strong metacognitive skills through experience |
+| first-timer | 0.35 | Novices lack domain-specific metacognitive strategies |
+| elderly-user | 0.60 | Life experience provides general metacognition despite tech unfamiliarity |
+| impatient-user | 0.25 | Impatience conflicts with reflective self-monitoring |
+| screen-reader-user | 0.75 | Accessibility navigation requires strategic planning |
+| mobile-user | 0.45 | Touch interaction somewhat reduces reflective planning |
+| anxious-user | 0.55 | Anxiety can either enhance or impair metacognition |
+
+## Implementation in CBrowser
+
+### State Tracking
+
+```typescript
+interface MetacognitiveState {
+  currentGoal: string;
+  subGoals: string[];
+  progressEstimate: number;  // 0-1
+  strategySwitches: number;
+  failedAttemptsSinceSwitch: number;
+  exploredPaths: Set<string>;
+  mentalMapQuality: number;  // 0-1
+  lastMonitoringCheck: number;  // timestamp
+}
+```
+
+### Behavioral Modifiers
+
+- **Planning pause**: High metacognition adds 1-3 second pause before first action on new page
+- **Progress checking**: Frequency of goal-state comparison based on trait level
+- **Strategy switching**: Threshold for abandoning current approach (3-5 attempts for low, 1-2 for high)
+- **Path memory**: High metacognition maintains explored path history to avoid revisiting
+
+## See Also
+
+- [Trait-WorkingMemory](Trait-WorkingMemory) - Capacity for maintaining goals and state
+- [Trait-ProceduralFluency](Trait-ProceduralFluency) - Executing learned procedures efficiently
+- [Trait-TransferLearning](Trait-TransferLearning) - Applying strategies across domains
+- [Trait-Comprehension](Trait-Comprehension) - Understanding interface conventions
+- [Cognitive-User-Simulation](../Cognitive-User-Simulation) - Main simulation documentation
+- [Persona-Index](../personas/Persona-Index) - Pre-configured trait combinations
+
+## Bibliography
+
+Azevedo, R., & Cromley, J. G. (2004). Does training on self-regulated learning facilitate students' learning with hypermedia? *Journal of Educational Psychology*, 96(3), 523-535. https://doi.org/10.1037/0022-0663.96.3.523
+
+Bandura, A. (1986). *Social foundations of thought and action: A social cognitive theory*. Prentice-Hall.
+
+Dunlosky, J., & Metcalfe, J. (2009). *Metacognition*. SAGE Publications.
+
+Flavell, J. H. (1979). Metacognition and cognitive monitoring: A new area of cognitive-developmental inquiry. *American Psychologist*, 34(10), 906-911. https://doi.org/10.1037/0003-066X.34.10.906
+
+Nelson, T. O., & Narens, L. (1990). Metamemory: A theoretical framework and new findings. In G. H. Bower (Ed.), *The psychology of learning and motivation* (Vol. 26, pp. 125-173). Academic Press.
+
+Schraw, G., & Dennison, R. S. (1994). Assessing metacognitive awareness. *Contemporary Educational Psychology*, 19(4), 460-475. https://doi.org/10.1006/ceps.1994.1033
+
+Simon, H. A. (1956). Rational choice and the structure of the environment. *Psychological Review*, 63(2), 129-138. https://doi.org/10.1037/h0042769
+
+Veenman, M. V. J., Van Hout-Wolters, B. H. A. M., & Afflerbach, P. (2006). Metacognition and learning: Conceptual and methodological considerations. *Metacognition and Learning*, 1(1), 3-14. https://doi.org/10.1007/s11409-006-6893-0
+
+Winne, P. H., & Hadwin, A. F. (1998). Studying as self-regulated learning. In D. J. Hacker, J. Dunlosky, & A. C. Graesser (Eds.), *Metacognition in educational theory and practice* (pp. 277-304). Lawrence Erlbaum Associates.