Pedagogical Journey

What this skill does

# Pedagogical Journey

Explain solutions through discovery—showing **how insights emerged** rather than exhaustive technical details.

## Core Principle

Show the journey of discovery without exhaustion. Focus on the "why" rather than the "what", highlighting key insights and decision points.

## Required Sections

Every explanation MUST include:

### 1. High-Level Summary (2-3 sentences)

Start with a concise overview of what was accomplished. Focus on the "what" and "why" before the "how".

### 2. The Journey & Discovery Process (2-4 sentences)

Brief context on how the solution emerged:
- What led to the approach taken
- Key insights or turning points during implementation
- Alternative approaches considered (if relevant)
- How testing or debugging shaped the final solution

**Examples:**
- "Initially I tried X, but discovered Y limitation which led to the current Z approach"
- "The key insight came from noticing [pattern/behavior], which informed..."
- "During testing, I found [issue], which revealed the need for..."

Keep this concise—focus on the most impactful decision points.

## Optional Sections

Include when they add value:

### 3. Visual Overview
Diagrams clarifying understanding: architecture diagrams, flow charts, file structure trees, sequence diagrams.

**Skip if:** Explanation is simple enough without visuals or words suffice.

### 4. Key Changes
Organize changes by module/component, purpose, and impact.

**Skip if:** Change is isolated to one component or already covered in Journey section.

### 5. Technical Details
Implementation specifics: new functions/classes, modified behavior (before/after), integration points.

**Important**: Don't include full code listings—reference file paths and line numbers instead (e.g., `tracking.lua:45`).

**Skip if:** Implementation is straightforward or user didn't ask for deep technical details.

### 6. What to Try Next
2-3 concrete suggestions for testing, building, or exploring further.

**Skip if:** No clear next steps or user didn't ask for guidance.

## Format-Specific Guidelines

### As HTML
1. Summary + Journey at top (required, always visible)
2. Other sections only if they add value
3. Use Mermaid flowcharts for decision trees
4. Collapsible sections for technical details
5. Color coding: Gold for insights, Green for outcomes, Gray for details

### As Markdown
1. Use standard headers (`##`, `###`)
2. Use `> **Journey Insight:**` blockquotes for key discoveries
3. Use mermaid code fences for diagrams
4. Use tables for before/after comparisons
5. Only include optional sections when valuable

## Section Selection Logic

**Always include:**
- ✅ High-Level Summary
- ✅ The Journey & Discovery Process

**Consider including when:**
- 📊 Visual Overview: Complex architecture, multiple components, or process flows
- 🔧 Key Changes: Multiple modules modified or changes span different layers
- ⚙️ Technical Details: Non-trivial implementation or user specifically asked
- 🚀 What to Try Next: Clear actionable next steps or areas to explore

**Skip optional sections when:**
- ❌ Information already covered in required sections
- ❌ Change is simple and self-explanatory
- ❌ Would add noise without adding clarity
- ❌ User didn't express interest in that level of detail

## General Guidelines

- **Be intentionally concise**: Aim for clarity over completeness
- **Show the journey, don't narrate every step**: Highlight key discoveries and decision points
- **Connect decisions to outcomes**: Help users understand why choices were made
- **Use formatting liberally**: Headers, bullets, bold text for scanning
- **Avoid walls of text**: Break up long sections with whitespace
- **Adapt to format**: Use format-specific features to enhance clarity

## Minimal Example

```
I've fixed the popup issue where they were closing immediately after opening.

**How we got here:**
Initially I suspected the popup code itself, but debugging revealed the CursorMoved autocommand was closing popups globally. The fix adds a buffer name check to only close popups when cursor moves in source files, not within the popup itself.
```

## Format Combinations

You can combine this with other output formats:
- "EXPLAIN HTML" → Use this structure in HTML format
- "EXPLAIN markdown" → Use this structure in markdown
- "EXPLAIN + [another format]" → Apply both modes together

For detailed examples and advanced patterns, see [reference.md](reference.md).