learnship 1.9.0

package/skills/agentic-learning/references/learning-science.md

@@ -0,0 +1,190 @@
+# Learning Science Reference
+
+This file provides the agent with context on the four evidence-based learning techniques that power `agentic-learning`. Use it to explain the *why* behind each action when the user asks.
+
+---
+
+## The core problem: illusion of competence
+
+When we read a fluent, well-structured answer from an AI model, it *feels* like we've learned. The information seems clear, logical, complete. But fluency in reading is not the same as encoding in memory or building understanding.
+
+This is called the **illusion of competence**: we mistake the ease of *consuming* information for the ability to *use* it. Students who re-read notes feel more confident than students who test themselves — but they perform worse on exams.
+
+**The fix:** learning requires effortful, active processing. The techniques below are not harder because they're poorly designed — they're harder because difficulty is the mechanism.
+
+---
+
+## Technique 1: Retrieval
+
+**What it is:** The act of pulling information *out* of memory rather than putting it *in*.
+
+**The research:** In a landmark study, students given a passage to read were divided into two groups: one group re-read it repeatedly; the other read it once and then tried to recall it from memory. The recall group remembered significantly more — even though they spent less time with the material.
+
+**Why it works:** Retrieval strengthens the memory trace. Every time you successfully recall something, you make it easier to recall again. Re-reading does not do this — it only creates a familiarity signal, not a retrieval pathway.
+
+**How the agent applies it:**
+- In `learn`: ask the user to explain or recall before providing the answer
+- In `quiz`: present questions from the current codebase; user answers before seeing corrections
+- In `explain-first`: user narrates the code in their own words before the agent comments
+
+---
+
+## Technique 2: Spacing
+
+**What it is:** Distributing learning over time rather than concentrating it in one session (cramming).
+
+**The research:** Memory decays over time following the "forgetting curve" (Ebbinghaus, 1885). But each retrieval resets and extends the curve. Retrieving a concept after a delay is harder than retrieving it immediately — and that difficulty is precisely what strengthens the trace.
+
+**Why it works:** Spaced practice forces the brain to rebuild the memory pathway from a weaker state, which leads to stronger long-term retention than massed practice.
+
+**How the agent applies it:**
+- In `space`: after a session, categorizes concepts by confidence level and schedules revisit prompts (tomorrow, 3 days, 1 week)
+- Writes a `docs/revisit.md` file so the user has a concrete artifact to return to
+
+---
+
+## Technique 3: Generation
+
+**What it is:** Producing an answer — even an incorrect one — before seeing the correct answer.
+
+**The research:** In studies on "generation effect," students given word pairs like "rapid - ____" where they had to generate the word "fast" from a cue remembered the pair better than students given both words. Generating the answer, even incorrectly, creates a stronger memory trace than passively receiving it.
+
+**Why it works:** The attempt to generate activates relevant knowledge and creates stronger encoding. Getting it wrong and then seeing the correct answer is more effective than never having to produce anything.
+
+**How the agent applies it:**
+- In `learn`: give partial examples (first line of code, function signature, first word) and ask the user to complete them
+- In `struggle`: give the minimum context needed and ask the user to produce the solution, escalating hints only when truly stuck
+- In `quiz`: fill-in-the-blank and predict-the-output questions
+
+---
+
+## Technique 4: Reflection
+
+**What it is:** Structured self-assessment against a learning goal.
+
+**The research:** Students who engaged in structured reflection — asking "how am I learning?", "what is my goal?", and "what are the gaps?" — showed measurably better outcomes than students who reviewed the same material without reflection.
+
+**Why it works:** Reflection forces metacognition: thinking about your own thinking. It surfaces gaps that passive review hides and creates a feedback loop between effort and outcome.
+
+**How the agent applies it:**
+- In `reflect`: ask the three structured questions in sequence and generate a gap analysis
+- In `struggle`: after revealing the answer, ask "can you re-implement this from scratch?"
+- In `either-or`: ask the user to articulate rationale and expected consequences, which is itself a reflective act
+
+---
+
+## Technique 5: Interleaving
+
+**What it is:** Deliberately mixing different topics or problem types within a single study session rather than studying one topic to completion before moving to the next (blocked practice).
+
+**The research:** Psychology professor Doug Rohrer found that "interleaving produced better scores on final tests of learning." The reason: interleaving forces the learner to discriminate between problem types and select the appropriate strategy each time, rather than assuming the same solution works for every problem in a block.
+
+**The subtle trap:** Blocked practice *feels* more effective because it produces immediate fluency. Interleaving feels harder and less productive during the session — but results in significantly better long-term retention and transfer. This is another form of *desirable difficulty*.
+
+**How the agent applies it:**
+- In `interleave`: pull concepts from different past sessions and mix them in a single quiz or recall exercise
+- In `space`: when scheduling revisits, deliberately pair concepts from different domains to prevent pattern-matching shortcuts
+
+---
+
+## Technique 6: Cognitive Load Management
+
+**What it is:** Recognising that working memory is severely limited (typically 4–7 items at once) and structuring learning to stay within that limit.
+
+**The research:** Cognitive load theory (Sweller, 1988; applied to technical learning by Frederick Reif) posits that our working memory can only hold and process a small number of elements simultaneously. When cognitive load exceeds capacity, learning breaks down — not because the learner is incapable, but because the architecture of human memory is being overwhelmed.
+
+**Three types of cognitive load:**
+1. **Intrinsic** — inherent complexity of the material (e.g., async event loops)
+2. **Extraneous** — complexity from poor presentation (e.g., unclear variable names)
+3. **Germane** — productive effort spent building schemas and mental models
+
+**The implication:** effective teaching reduces extraneous load and stays within intrinsic load limits, so that germane load (real learning) can happen. When a learner is overwhelmed, the answer is not to explain more — it is to decompose the problem into smaller working-memory-sized chunks.
+
+**How the agent applies it:**
+- In `learn`: if the topic is complex, break it into sub-concepts and teach one at a time
+- In `struggle`: hints are calibrated so each hint adds one element, not five
+- In `cognitive-load`: explicit action to help decompose an overwhelming problem into manageable pieces
+
+---
+
+## Technique 7: Metacognition
+
+**What it is:** Thinking about your own thinking — the awareness and active monitoring of your own learning process.
+
+**The research:** Educationally relevant metacognitive skills include: evaluating progress on a task, identifying where you are stuck, knowing when you don't understand something, and selecting the right strategy for the right kind of problem. The Learning Skills curriculum (Mannion & McAllister) embedded metacognition, self-regulation, and oracy across a whole school and produced GCSE results 10.9 percentage points higher than a control cohort over eight years. For disadvantaged students, the gap improvement was 23.3 percentage points.
+
+**The distinction from reflection:** Reflection looks *backward* ("what did I learn?"). Metacognition operates *in real time* ("how am I learning right now? Am I actually understanding this or just recognising it?"). Both are necessary; neither replaces the other.
+
+**How the agent applies it:**
+- In `reflect`: the third question ("what are the gaps?") is explicitly metacognitive
+- In `learn`: before teaching, ask "do you feel like you understand this, or does it just feel familiar?"
+- Distinguishing *familiarity* from *understanding* is the single most important metacognitive move in AI-assisted learning
+
+---
+
+## Technique 8: Oracy
+
+**What it is:** Oracy is the ability to articulate ideas clearly and precisely in spoken or written language. It is not merely a communication skill — it is a metacognitive diagnostic tool. When a learner attempts to explain something in their own words, they surface in real time exactly what they understand versus what they merely recognise.
+
+**The research:** Mannion & McAllister's Learning Skills curriculum embedded oracy explicitly alongside metacognition and self-regulation as a triad of skills. The reason oracy belongs in that triad: you cannot self-regulate your learning if you cannot articulate where your understanding breaks down. Lakhani notes that schools doing the best pastoral and academic work integrate "evaluation, reasoning, public speaking, and communication" into subject delivery — not as separate modules but as the *medium* through which knowledge is built.
+
+**The mechanism:** The Protégé Effect — explaining something to another person (or to an agent) forces more complete and accurate encoding than reading or listening alone. When you discover mid-explanation that you can't finish a sentence, that is not failure; that is the system working. The gap you found is the thing that needs to be learned.
+
+**The key distinction from retrieval:** Retrieval asks "can you recall this?". Oracy asks "can you express this clearly enough that someone who doesn't know it would understand it?". The second bar is higher. Passing the retrieval test does not guarantee passing the oracy test.
+
+**How the agent applies it:**
+- In `explain-first`: the core mechanic — user explains before agent comments; agent pushes for precision when explanation is vague
+- In `learn`: after the explanation phase, the generation prompt can ask the user to "explain this line to a colleague" rather than just write code
+- If the user gives a vague explanation anywhere, ask one precision-pushing follow-up: "You said it 'handles it' — can you say exactly what it does to handle it?"
+
+---
+
+## Technique 9: Formative Feedback
+
+**What it is:** Feedback that is timely, specific, and tied to a learning goal — as opposed to summative feedback (a grade after the fact) or binary feedback ("correct/incorrect" with no further information).
+
+**The research:** Hattie & Timperley (2007) conducted a meta-analysis of educational interventions and found that feedback is one of the most powerful influences on achievement — but only when it operates at the right level. They identified four feedback levels:
+1. **Task level** — "this answer is wrong" (least useful)
+2. **Process level** — "the approach you used doesn't work here because..." (most useful for learning)
+3. **Self-regulation level** — "what strategy could you use to check this yourself?" (builds independence)
+4. **Self level** — "you're so smart" (can be actively harmful; see growth mindset)
+
+The vast majority of AI feedback defaults to task level (correct/incorrect) or self level ("great job!"). Both are the least effective.
+
+**Lakhani's framing:** Formative assessment is ongoing and actionable — it changes what the learner does next. Summative assessment is retrospective and final. The distinction matters because AI, left to its natural behaviour, produces summative-style responses to every answer: a verdict, not a guide.
+
+**The growth mindset caveat (Dweck, 2006):** Generic praise of ability — "you're so smart", "you're a natural" — actively undermines motivation and resilience. It creates a fixed mindset: learners attribute success to inherent ability, and therefore interpret failure as evidence of lack of ability. Praise of *process* — "you found the right strategy", "that was sharp reasoning", "you identified the key mechanism" — creates a growth mindset: failure is just a strategy that didn't work yet. This distinction applies to every feedback interaction in this skill.
+
+**How the agent applies it:**
+- In `learn`: step 4 requires formative, anchored feedback on the user's initial answer
+- In `quiz`: step 4 requires process-level feedback after every question
+- In `struggle`: hints and post-reveal comments should praise the specific reasoning the user applied, not the outcome
+- In `reflect`: the gap analysis is formative by design — it asks what to do next, not what the score was
+- **Never use**: "correct!", "great job!", "you're really good at this" as standalone responses
+- **Always anchor to**: what specifically the user understood, why it matters, what to try if they were wrong
+
+---
+
+## The neurological basis
+
+Sustained mental effort is positively correlated with brain growth. A neuroscience study of London taxi drivers (who must memorize 26,000 streets to pass "The Knowledge" exam) found enlarged hippocampal regions compared to non-taxi drivers. The structural changes correlated with years of experience — the brain literally grows in response to the kind of effortful spatial memory work required by the job.
+
+Sleep plays a critical role in memory consolidation. Neuroscience professor Matthew Walker (*Why We Sleep*, 2018) argues that memories are consolidated during sleep — complex memories during REM sleep, new information during slow-wave sleep (SWS). Sleep deprivation reduces both encoding and retrieval. The practical implication: a learning session followed by adequate sleep is more effective than two sessions with no sleep between them.
+
+**The implication for software learning:** understanding a codebase, an architecture, or a new language requires the same kind of active, effortful construction of mental models. AI can provide the scaffolding, but the user must do the building. And the brain needs rest to cement what was built.
+
+---
+
+## Primary sources
+
+- Roediger, H.L. & Karpicke, J.D. (2006). "Test-Enhanced Learning." *Psychological Science*, 17(3), 249–255.
+- Ebbinghaus, H. (1885). *Über das Gedächtnis*. (Memory: A Contribution to Experimental Psychology.)
+- Maguire, E.A. et al. (2000). "Navigation-related structural change in the hippocampi of taxi drivers." *PNAS*, 97(8), 4398–4403.
+- Dweck, C.S. (2006). *Mindset: The New Psychology of Success.* Random House. — Growth mindset only produces results when praise is tied to process and strategy, not ability. Generic ability praise can actively undermine resilience.
+- Hattie, J. & Timperley, H. (2007). "The Power of Feedback." *Review of Educational Research*, 77(1), 81–112. — Four levels of feedback; process-level feedback is most effective for learning; self-level feedback (praise of ability) is least effective.
+- Brown, P.C., Roediger, H.L., & McDaniel, M.A. (2014). *Make It Stick: The Science of Successful Learning.* Harvard University Press.
+- Sweller, J. (1988). "Cognitive Load During Problem Solving." *Cognitive Science*, 12(2), 257–285.
+- Rohrer, D. & Taylor, K. (2007). "The shuffling of mathematics problems improves learning." *Instructional Science*, 35(6), 481–498.
+- Walker, M. (2018). *Why We Sleep.* Penguin.
+- Mannion, J. & McAllister, K. (2020). "The Learning Skills Curriculum." *Impact: Journal of the Chartered College of Teaching.*
+- Lakhani, P. (2021). *Inadequate: The education system is failing our children and what we can do about it.* John Catt Educational. — Chapters 9 (Learning science) and 10 (Education 4.0) provide an accessible synthesis of cognitive load theory, interleaving, metacognition, sleep and memory, growth mindset, and the role of AI in personalised learning. Lakhani grounds these in the context of designing AI-powered education systems (CENTURY Tech) and argues that technology must operate at human speed to be effective.

package/skills/agentic-learning/references/struggle-ladder.md

@@ -0,0 +1,140 @@
+# Struggle Ladder Reference
+
+This file defines the hint escalation system used by the `struggle` action. The goal is to keep the user in productive struggle as long as possible, revealing only what is needed to unblock them — never more.
+
+---
+
+## Core principle
+
+The struggle is not a failure state. It is the mechanism of learning. Each attempt — even a wrong one — builds a stronger memory trace than passively receiving the answer. The agent's job is to stay at the edge of the user's competence: challenging enough to require effort, supportive enough to prevent abandonment.
+
+---
+
+## Default configuration
+
+- **Default hints before reveal:** 3
+- **User can extend:** yes — say "more hints" to get additional conceptual nudges before the reveal
+- **User can skip:** yes — say "show me" or "I give up" to jump directly to the full solution
+- **User can increase difficulty:** yes — say "harder" to reduce the specificity of each hint
+
+---
+
+## The four levels
+
+### Level 0 — The problem statement
+
+Before any hints, the agent restates the task in clean terms and confirms the user understands *what* they're trying to accomplish. If the user doesn't know where to start at all, Level 0 surfaces that.
+
+**What the agent says:**
+- "Let's make sure we're aligned on what we're building. In your own words, what is this function/system supposed to do?"
+- If they can't answer: give a one-sentence description of the goal. Then ask: "What would you try first?"
+
+---
+
+### Level 1 — Conceptual direction
+
+Point the user toward the right *area* of thinking without naming the solution or the technique.
+
+**What the agent gives:**
+- The domain or category of the solution ("this is fundamentally about ordering", "think about what data structure would let you do X in constant time")
+- A question that reframes the problem ("what would need to be true for this to work?", "what happens if the input is empty?")
+- A reference to something the user already knows that's related ("remember how we handled the similar case in X?")
+
+**What the agent does NOT give:**
+- The name of the algorithm or pattern
+- Any code
+- The structure of the solution
+
+---
+
+### Level 2 — Structural hint
+
+Describe what the solution *looks like* without writing it. This is about shape and structure, not content.
+
+**What the agent gives:**
+- The overall shape: "you'll need a loop here", "this probably has two phases: first X, then Y"
+- The type signature or interface: "the function takes A and returns B"
+- A constraint that narrows the search space: "you don't need recursion here", "this can be done in a single pass"
+- A partial pseudocode sketch in plain English (not code)
+
+**What the agent does NOT give:**
+- Actual code in any language
+- The specific variable names or logic
+
+---
+
+### Level 3 — Partial code
+
+Give the skeleton. Leave the meaningful parts blank for the user to fill in.
+
+**What the agent gives:**
+- The function signature
+- The first line or setup code
+- Loop or conditional skeleton with `# your logic here` placeholders
+- The return statement pattern without the expression
+
+**Example:**
+```python
+def binary_search(arr, target):
+    left, right = 0, len(arr) - 1
+    while left <= right:
+        mid = # your logic here
+        if arr[mid] == target:
+            # what do you return?
+        elif # condition:
+            # adjust left or right?
+        else:
+            # adjust the other one?
+    return -1
+```
+
+**What the agent does NOT give:**
+- The filled-in logic
+- Comments explaining what each blank should contain (unless the user asks)
+
+---
+
+### Reveal — Full solution
+
+Only shown when:
+- The user has worked through all 3 hints and is still stuck, AND says "show me" or "I give up"
+- OR the user explicitly requests a reveal at any point
+
+**What the agent gives:**
+- The complete, working solution
+- A brief explanation of each meaningful part
+- The key insight that makes it work
+
+**Mandatory follow-up after reveal:**
+Always ask: "Now that you've seen it — close this and try to re-implement it from scratch, without looking. That's the part that makes it stick."
+
+---
+
+## Extended hints (user says "more hints")
+
+If the user asks for more hints after Level 3 but before reveal, give up to 2 additional micro-hints:
+
+- **Micro-hint A:** Focus on the single hardest part — give one more structural clue about just that piece
+- **Micro-hint B:** Give a concrete analogy from a different domain that maps to the solution structure
+
+After Micro-hint B, only the reveal remains.
+
+---
+
+## "Harder" mode
+
+If the user says "harder" at any point:
+- Level 1 becomes purely Socratic: questions only, no directional hints
+- Level 2 becomes conceptual direction (what would have been Level 1)
+- Level 3 becomes structural hint (what would have been Level 2)
+- Reveal is the only way to see actual code
+
+---
+
+## Calibrating difficulty
+
+The agent should also watch for signs of unproductive struggle — frustration without progress — and adjust:
+
+- If the user has been stuck for a long time with no meaningful attempts, it is acceptable to offer a hint one level earlier than scheduled
+- If the user is making genuine attempts (even wrong ones), stay at the current level longer
+- If the user's attempt is partially correct, build on what they got right: "That's the right idea for the first part — what about the case where X?"

package/skills/impeccable/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: impeccable
+description: >
+  A design quality system for frontend interfaces. 18 focused actions for
+  auditing, refining, and elevating UI quality. Invoke with @impeccable
+  followed by one of: adapt, animate, audit, bolder, clarify, colorize,
+  critique, delight, distill, extract, frontend-design, harden, normalize,
+  onboard, optimize, polish, quieter, or teach-impeccable.
+license: MIT
+compatibility: Works with Windsurf Cascade, Claude Code, and any AgentSkills-compatible agent.
+metadata:
+  author: favio-vazquez
+  version: "1.0"
+---
+
+# Impeccable
+
+A design quality system composed of 18 focused actions for auditing, refining,
+and elevating frontend interfaces. Each action is a specialist — invoke the one
+that matches your current need.
+
+**Core principle:** Good design is intentional. Every action here resists vague
+"make it better" requests by applying a specific, disciplined lens. Use
+`frontend-design` as the foundation — all other actions reference its
+principles and anti-patterns.
+
+---
+
+## Actions
+
+### `adapt` — Responsive & cross-platform adaptation
+[adapt/SKILL.md](adapt/SKILL.md)
+
+### `animate` — Purposeful motion & micro-interactions
+[animate/SKILL.md](animate/SKILL.md)
+
+### `audit` — Comprehensive quality audit
+[audit/SKILL.md](audit/SKILL.md)
+
+### `bolder` — Amplify safe or boring designs
+[bolder/SKILL.md](bolder/SKILL.md)
+
+### `clarify` — UX copy, microcopy & labels
+[clarify/SKILL.md](clarify/SKILL.md)
+
+### `colorize` — Strategic color addition
+[colorize/SKILL.md](colorize/SKILL.md)
+
+### `critique` — UX effectiveness evaluation
+[critique/SKILL.md](critique/SKILL.md)
+
+### `delight` — Moments of joy & personality
+[delight/SKILL.md](delight/SKILL.md)
+
+### `distill` — Strip to essence
+[distill/SKILL.md](distill/SKILL.md)
+
+### `extract` — Reusable components & design tokens
+[extract/SKILL.md](extract/SKILL.md)
+
+### `frontend-design` — Design foundation & principles
+[frontend-design/SKILL.md](frontend-design/SKILL.md)
+
+### `harden` — Resilience, i18n & edge cases
+[harden/SKILL.md](harden/SKILL.md)
+
+### `normalize` — Design system consistency
+[normalize/SKILL.md](normalize/SKILL.md)
+
+### `onboard` — Onboarding flows & empty states
+[onboard/SKILL.md](onboard/SKILL.md)
+
+### `optimize` — Performance & loading speed
+[optimize/SKILL.md](optimize/SKILL.md)
+
+### `polish` — Final quality pass before shipping
+[polish/SKILL.md](polish/SKILL.md)
+
+### `quieter` — Tone down aggressive designs
+[quieter/SKILL.md](quieter/SKILL.md)
+
+### `teach-impeccable` — Project design context setup
+[teach-impeccable/SKILL.md](teach-impeccable/SKILL.md)
+
+---
+
+## How to use
+
+Invoke with the action that matches your need:
+
+```
+@impeccable audit          — full quality audit report
+@impeccable polish         — final pass before shipping
+@impeccable critique       — UX effectiveness review
+@impeccable normalize      — align with design system
+@impeccable frontend-design — apply design foundation principles
+```
+
+When in doubt, start with `@impeccable audit` to get a full picture, then
+use the specific action it recommends.
+
+---
+
+## After running any impeccable action
+
+When an impeccable action produces a list of recommendations, improvements, or issues — always close with this suggestion:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ impeccable ► RECOMMENDATIONS READY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[N] improvements identified. To apply them in a traceable, structured way:
+
+▶ Run `/new-milestone` to create a dedicated "UI Polish" or "Design Quality" milestone.
+  This turns these recommendations into versioned phases with plans, commits, and
+  verification — so nothing gets lost and every improvement is auditable.
+
+Or apply them directly now and use `/decision-log` to record what was changed and why.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+This applies after: `audit`, `critique`, `polish`, `normalize`, `harden`, `adapt`, `optimize`, `bolder`, `quieter`, `colorize`, `clarify`, `delight`, `onboard`, `animate`, `distill`, `extract`.
+
+For `teach-impeccable` and `frontend-design` (which set up context, not produce recommendations), skip this suggestion.

package/skills/impeccable/adapt/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: adapt
+description: Adapt designs to work across different screen sizes, devices, contexts, or platforms. Ensures consistent experience across varied environments.
+args:
+  - name: target
+    description: The feature or component to adapt (optional)
+    required: false
+  - name: context
+    description: What to adapt for (mobile, tablet, desktop, print, email, etc.)
+    required: false
+user-invokable: true
+---
+
+Adapt existing designs to work effectively across different contexts - different screen sizes, devices, platforms, or use cases.
+
+## Assess Adaptation Challenge
+
+Understand what needs adaptation and why:
+
+1. **Identify the source context**:
+   - What was it designed for originally? (Desktop web? Mobile app?)
+   - What assumptions were made? (Large screen? Mouse input? Fast connection?)
+   - What works well in current context?
+
+2. **Understand target context**:
+   - **Device**: Mobile, tablet, desktop, TV, watch, print?
+   - **Input method**: Touch, mouse, keyboard, voice, gamepad?
+   - **Screen constraints**: Size, resolution, orientation?
+   - **Connection**: Fast wifi, slow 3G, offline?
+   - **Usage context**: On-the-go vs desk, quick glance vs focused reading?
+   - **User expectations**: What do users expect on this platform?
+
+3. **Identify adaptation challenges**:
+   - What won't fit? (Content, navigation, features)
+   - What won't work? (Hover states on touch, tiny touch targets)
+   - What's inappropriate? (Desktop patterns on mobile, mobile patterns on desktop)
+
+**CRITICAL**: Adaptation is not just scaling - it's rethinking the experience for the new context.
+
+## Plan Adaptation Strategy
+
+Create context-appropriate strategy:
+
+### Mobile Adaptation (Desktop → Mobile)
+
+**Layout Strategy**:
+- Single column instead of multi-column
+- Vertical stacking instead of side-by-side
+- Full-width components instead of fixed widths
+- Bottom navigation instead of top/side navigation
+
+**Interaction Strategy**:
+- Touch targets 44x44px minimum (not hover-dependent)
+- Swipe gestures where appropriate (lists, carousels)
+- Bottom sheets instead of dropdowns
+- Thumbs-first design (controls within thumb reach)
+- Larger tap areas with more spacing
+
+**Content Strategy**:
+- Progressive disclosure (don't show everything at once)
+- Prioritize primary content (secondary content in tabs/accordions)
+- Shorter text (more concise)
+- Larger text (16px minimum)
+
+**Navigation Strategy**:
+- Hamburger menu or bottom navigation
+- Reduce navigation complexity
+- Sticky headers for context
+- Back button in navigation flow
+
+### Tablet Adaptation (Hybrid Approach)
+
+**Layout Strategy**:
+- Two-column layouts (not single or three-column)
+- Side panels for secondary content
+- Master-detail views (list + detail)
+- Adaptive based on orientation (portrait vs landscape)
+
+**Interaction Strategy**:
+- Support both touch and pointer
+- Touch targets 44x44px but allow denser layouts than phone
+- Side navigation drawers
+- Multi-column forms where appropriate
+
+### Desktop Adaptation (Mobile → Desktop)
+
+**Layout Strategy**:
+- Multi-column layouts (use horizontal space)
+- Side navigation always visible
+- Multiple information panels simultaneously
+- Fixed widths with max-width constraints (don't stretch to 4K)
+
+**Interaction Strategy**:
+- Hover states for additional information
+- Keyboard shortcuts
+- Right-click context menus
+- Drag and drop where helpful
+- Multi-select with Shift/Cmd
+
+**Content Strategy**:
+- Show more information upfront (less progressive disclosure)
+- Data tables with many columns
+- Richer visualizations
+- More detailed descriptions
+
+### Print Adaptation (Screen → Print)
+
+**Layout Strategy**:
+- Page breaks at logical points
+- Remove navigation, footer, interactive elements
+- Black and white (or limited color)
+- Proper margins for binding
+
+**Content Strategy**:
+- Expand shortened content (show full URLs, hidden sections)
+- Add page numbers, headers, footers
+- Include metadata (print date, page title)
+- Convert charts to print-friendly versions
+
+### Email Adaptation (Web → Email)
+
+**Layout Strategy**:
+- Narrow width (600px max)
+- Single column only
+- Inline CSS (no external stylesheets)
+- Table-based layouts (for email client compatibility)
+
+**Interaction Strategy**:
+- Large, obvious CTAs (buttons not text links)
+- No hover states (not reliable)
+- Deep links to web app for complex interactions
+
+## Implement Adaptations
+
+Apply changes systematically:
+
+### Responsive Breakpoints
+
+Choose appropriate breakpoints:
+- Mobile: 320px-767px
+- Tablet: 768px-1023px
+- Desktop: 1024px+
+- Or content-driven breakpoints (where design breaks)
+
+### Layout Adaptation Techniques
+
+- **CSS Grid/Flexbox**: Reflow layouts automatically
+- **Container Queries**: Adapt based on container, not viewport
+- **`clamp()`**: Fluid sizing between min and max
+- **Media queries**: Different styles for different contexts
+- **Display properties**: Show/hide elements per context
+
+### Touch Adaptation
+
+- Increase touch target sizes (44x44px minimum)
+- Add more spacing between interactive elements
+- Remove hover-dependent interactions
+- Add touch feedback (ripples, highlights)
+- Consider thumb zones (easier to reach bottom than top)
+
+### Content Adaptation
+
+- Use `display: none` sparingly (still downloads)
+- Progressive enhancement (core content first, enhancements on larger screens)
+- Lazy loading for off-screen content
+- Responsive images (`srcset`, `picture` element)
+
+### Navigation Adaptation
+
+- Transform complex nav to hamburger/drawer on mobile
+- Bottom nav bar for mobile apps
+- Persistent side navigation on desktop
+- Breadcrumbs on smaller screens for context
+
+**IMPORTANT**: Test on real devices, not just browser DevTools. Device emulation is helpful but not perfect.
+
+**NEVER**:
+- Hide core functionality on mobile (if it matters, make it work)
+- Assume desktop = powerful device (consider accessibility, older machines)
+- Use different information architecture across contexts (confusing)
+- Break user expectations for platform (mobile users expect mobile patterns)
+- Forget landscape orientation on mobile/tablet
+- Use generic breakpoints blindly (use content-driven breakpoints)
+- Ignore touch on desktop (many desktop devices have touch)
+
+## Verify Adaptations
+
+Test thoroughly across contexts:
+
+- **Real devices**: Test on actual phones, tablets, desktops
+- **Different orientations**: Portrait and landscape
+- **Different browsers**: Safari, Chrome, Firefox, Edge
+- **Different OS**: iOS, Android, Windows, macOS
+- **Different input methods**: Touch, mouse, keyboard
+- **Edge cases**: Very small screens (320px), very large screens (4K)
+- **Slow connections**: Test on throttled network
+
+Remember: You're a cross-platform design expert. Make experiences that feel native to each context while maintaining brand and functionality consistency. Adapt intentionally, test thoroughly.
+