Cf Teach

/cf-teach

You are my personal teacher. Explain what just happened: $ARGUMENTS

Purpose

In any coding session, the AI does the heavy thinking — but the human often walks away with just the result, not the understanding. This skill breaks down the entire task in plain language, like a sharp friend explaining it over coffee. Not a textbook. Not documentation. A story about how and why.

Workflow

Step 0: Custom Guide

bash "${CLAUDE_PLUGIN_ROOT}/lib/load-custom-guide.sh" cf-teach

If the block above printed anything, apply only the ## Before, ## Rules, and ## After sections; if it shows the raw command instead of output, re-run that exact load-custom-guide.sh fence now.

Step 1: Load Config

Read config from two locations and merge (local overrides global):

1. Local: <project-root>/.coding-friend/config.json
2. Global: ~/.coding-friend/config.json

Extract settings with these defaults:

Language resolution: Read learn.language from config. If not set, fall back to top-level language. If neither is set, default to en.

Path resolution for outputDir:

• Run pwd to get the current working directory — substitute its actual output wherever $CWD appears below
• Starts with / → absolute path, use as-is
• Starts with ~/ → expand ~ to home directory
• Otherwise → relative to $CWD
• Always pass file_path as an absolute path to the cf-writer-deep agent

If outputDir directory doesn't exist, create it.

Step 2: Reconstruct the Session

Look back at the full conversation and identify:

• The main task or problem — what were we trying to accomplish?
• The approach taken — how did the AI solve it, step by step?
• Alternatives considered — what other approaches were mentioned, tried, or rejected?
• Key tools, frameworks, patterns, or techniques used
• Any mistakes, pivots, or wrong turns that occurred
• Tradeoffs — what was prioritized and what was sacrificed?
• How the pieces connect — how do the different parts of the solution relate?

If $ARGUMENTS is provided, focus the explanation on that specific topic or aspect of the session.

Step 3: Categorize and Determine Output File

Categorize

Use categories from config. Default categories:

Determine File Name

Choose a snake-case, meaningful file name that describes the story — not just the topic. File name must start with cf-teach-. Examples:

• cf-teach-how-i-debugged-the-race-condition.md
• cf-teach-why-we-chose-redis-over-postgres.md
• cf-teach-building-the-auth-middleware-from-scratch.md
• cf-teach-the-refactor-that-untangled-the-api-layer.md

File path: {outputDir}/{category}/YYYY-MM-DD-{name}.md

Backward compat: Existing files without a date prefix are still valid — do not rename them.

Check Existing Files

Before creating a new file, check if a relevant file already exists in the target category:

bash "${CLAUDE_PLUGIN_ROOT}/skills/cf-learn/scripts/list-learn-files.sh" "/absolute/path/to/outputDir"

For each potentially relevant file, read its first 20 lines. If the new teaching narrative fits an existing file, use a different name to avoid overwriting.

Step 4: Compose the Narrative (Show in Chat First)

Before saving anything, compose the full narrative and display it directly in the chat. This is the teaching moment — the human reads it here first.

The narrative must cover all 9 dimensions below. Write it as a flowing story, not a checklist. Use the actual project examples, not generic illustrations.

The 9 Dimensions

1. The Approach — and the Reasoning Behind It

Walk through what approach was taken and why. What was the starting point? What did the AI consider first? Don't just describe what was done — explain the thought process that led there. What made this approach feel right?

2. The Roads Not Taken

What other approaches were considered but rejected? Why? What was wrong with them, or what made them less suitable? This is often where the deepest learning lives — understanding why not to do something is as valuable as knowing why to do it.

3. How the Pieces Fit Together

If there was a plan, a draft, a structure — show how each piece connects to the others. Why is the order what it is? How does part A depend on or enable part B? A solution is rarely a single step; show the architecture of the thinking.

4. The Tools, Methods, and Frameworks

What specific tools, patterns, libraries, or techniques were used? Why those specifically, and not alternatives? What would have changed if different choices were made?

5. The Tradeoffs

Every decision has a cost. What was prioritized and what was sacrificed? Speed vs. correctness? Simplicity vs. flexibility? Show both sides of each key decision.

6. The Mess — Mistakes, Dead Ends, Corrections

What went wrong? What had to be revised or thrown out? How were those problems fixed? Don't sanitize the process — the mess is where the real learning lives.

7. Pitfalls to Watch For

If someone does something similar in the future, what should they watch out for? The "I wish someone told me this" advice. Specific, practical, based on what actually happened.

8. What an Expert Would Notice

What separates good thinking from average thinking here? What would a senior engineer or experienced practitioner immediately see in this work that a beginner would miss — about the approach, the tradeoffs, or the implementation?

9. What Transfers to Other Projects

What lessons from this work apply to completely different contexts? Connect the dots — what's the underlying principle that shows up across many types of problems?

Tone and style rules for the narrative:

• Write like a sharp friend explaining over coffee, not a technical author writing docs
• Use analogies, short stories, and real-world comparisons to make abstract ideas concrete
• Ground every concept in something from the actual session — no generic examples
• Make it engaging enough that the human actually wants to read it
• The human should finish and feel: "Now I actually understand what happened and why"

Step 5: Save the Doc

After displaying the narrative in chat, delegate to the cf-writer-deep agent (always — never cf-writer) to save it as a file.

Dispatch cf-writer-deep with the complete write spec as the prompt.

WRITE SPEC
----------
task: create
file_path: {absolute path to outputDir}/{category}/YYYY-MM-DD-{name}.md
language: {resolved language from Step 0}
content: |
  <The full narrative content — same as what was shown in chat>
auto_commit: {autoCommit from config}
commit_message: learn: <brief description of what was explained>

Content format — include frontmatter with tags, then the narrative:

---
title: "<Meaningful Title That Describes the Story>"
category: "<category-name>"
tags: [CF Teach, tag2, tag3]
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

# <Meaningful Title That Describes the Story>

<The full 9-dimension narrative — flowing prose, not a checklist>

Tag rules: Always include "CF Teach" as the first tag. Add 2-4 additional tags relevant to the topic.

Step 6: Confirm

After the cf-writer-deep agent completes, show the user:

1. Where the doc was saved (full path)
2. If auto-committed, show the commit message

Rules

• Always show the narrative in chat first — the human reads it here, not just from the file
• Always use cf-writer-deep (sonnet) — never cf-writer (haiku). The storytelling format requires nuanced tone and synthesis.
• Include frontmatter with tags — always include "CF Teach" tag plus 2-4 topic-relevant tags
• Use category subdirectories — output to {outputDir}/{category}/{name}.md (same structure as cf-learn)
• Use actual examples from the session — never generic illustrations
• Conversational tone — like explaining to a smart friend, not writing documentation
• Never skip dimensions — all 9 must be covered, even briefly, in every teaching doc
• NEVER delete or overwrite existing content — if a similar file exists, use a different name
• This is distinct from /cf-learn: cf-learn = concise reference notes; cf-teach = deep narrative story