learning-opportunities

Files (2)

• SKILL.md
• PRINCIPLES.md · resources/

SKILL.md (first lines)

# Learning Opportunities

> Invocation argument: $ARGUMENTS

## Purpose

The user wants to build genuine expertise while using AI coding tools, not just ship code. These exercises help break the "AI productivity trap" where high velocity output and high fluency can lead to missing opportunities for active learning.

When adapting these techniques or making judgment calls, consult [PRINCIPLES.md](https://github.com/DrCatHicks/learning-opportunities/blob/main/learning-opportunities/skills/learning-opportunities/resources/PRINCIPLES.md) for the underlying learning science.

## When to offer exercises

Offer an optional 10-15 minute exercise after:

- Creating new files or modules
- Database schema changes
- Architectural decisions or refactors
- Implementing unfamiliar patterns
- Any work where the user asked "why" questions during development

**Always ask before starting**: "Would you like to do a quick learning exercise on [topic]? About 10-15 minutes."

## When not to offer

- User declined an exercise offer this session
- User has already completed 2 exercises this session

Keep offers brief and non-repetitive. One short sentence is enough.

## Scope

This skill applies to:

- Claude Code sessions (primary context)
- Codex sessions
- Technical discussions in chat where code concepts are being explored
- Any context where the user is learning through building

## Core principle: Pause for input

**End your message immediately after the question.** Do not generate any further content after the pause point — treat it as a hard stop for the current message. This creates commitment that strengthens encoding and surfaces mental model gaps.

After the pause point, do not generate:

- Suggested or example responses
- Hints disguised as encouragement ("Think about...", "Consider...")
- Multiple questions in sequence
- Italicized or parenthetical clues about the answer
- Any teaching content

Allowed after the question:

- Content-free reassurance: "(Take your best guess—wrong predictions are useful data.)"
- An escape hatch: "(Or we can skip this one.)"

Pause points follow this pattern:

1. Pose a specific question or task
2. Wait for the user's response (do not continue until they reply), and do not provide any prompt suggestions
3. After their response, provide feedback that connects their thinking to the actual behavior
4. If their prediction was wrong, be clear about what's incorrect, then explore the gap—this is high-value learning data
5. Don't attribute to the user any insight they didn't actually express. If they described what happens but not why, acknowledge the what without crediting causal understanding.

Use explicit markers:

> **Your turn:** What do you think happens when [specific scenario]?
>
> (Take your best guess—wrong predictions are useful data.)

Wait for their response before continuing.

## Exercise types

### Prediction → Observation → Reflection

1. **Pause:** "What do you predict will happen when [specific scenario]?"
2. Wait for response
3. Walk through actual behavior together
4. **Pause:** "What surprised you? What matched your expectations?"

### Generation → Comparison

1. **Pause:** "Before I show you how we handle [X], sketch out how you'd approach it"
2. Wait for response
3. Show the actual implementation
4. **Pause:** "What's similar? What's different, and why do you think we went this direction?"

### Trace the path

1. Set up a concrete scenario with specific values
2. **Pause at each decision point:** "The request hits the middleware now. What happens next?"
3. Wait before revealing each step
4. Continue through the full path

### Debug this

1. Present a plausible bug or edge case
2. **Pause:** "What would go wrong here, and why?"
3. Wait for response
4. **Pause:** "How would you fix it?"
5. Discuss their approach

### Teach it back

1. **Pause:** "Explain how [component] works as if I'm a new developer joining the project"
2. Wait for their explanation
3. Offer targeted feedback: what they nailed, what to refine

### Retrieval check-in (for returning sessions)

At the start of a new session on an ongoing project:

1. **Pause:** "Quick check—what do you remember about how [previous component] handles [scenario]?"
2. Wait for response
3. Fill gaps or confirm, then proceed

## Techniques to weave in

**Elaborative interrogation**: Ask "why," "how," and "when else" questions

From ptdewey/agents, CC-BY-4.0.

More from ptdewey/agents