cf-teach · git:20260827.debd979 · 2026-08-27 · sha256 3e99bf40d7c86e96
cf-teach git:20260827.debd979A
Immutable. This exact content is served forever at /api/v1/blob/3e99bf40d7c86e96.
---
name: cf-teach
description: >
Personal teacher — after a task, explains what happened as a conversational narrative
(approach, alternatives, tradeoffs, pitfalls, lessons). Unlike /cf-learn (structured
notes), this is a deep-dive so the human understands what happened and why.
created: 2026-03-30
updated: 2026-08-27
---
# /cf-teach
> **CLI Requirement:** NONE — Works without `coding-friend-cli`. See [CLI requirements](../../../docs/cli-requirements.md) for the full matrix.
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
Custom guide — auto-loaded below (if the raw command shows instead of its output, run it yourself):
```!
bash "<plugin-root>/lib/load-custom-guide.sh" cf-teach
```
If output is not empty, integrate returned sections: `## Before` → before first step, `## Rules` → apply throughout, `## After` → after final step.
### 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:
| Setting | Default | Description |
| ------------------ | ------------------------------------------------------ | ------------------------------------------------------------------- |
| `learn.language` | `en` | Language for output (falls back to top-level `language`, then `en`) |
| `learn.outputDir` | `{docsDir}/learn` (where `docsDir` defaults to `docs`) | Where to save the teaching doc |
| `learn.autoCommit` | `false` | Auto git-commit after writing |
**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:
| Category | Folder name | Examples |
| --------- | ----------- | -------------------------------------- |
| Concepts | `concepts` | Dependency injection, event sourcing |
| Patterns | `patterns` | Repository pattern, observer pattern |
| Languages | `languages` | TypeScript generics, Python decorators |
| Tools | `tools` | Prisma migrations, Docker compose |
| Debugging | `debugging` | Race condition fix, memory leak hunt |
### 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
bash "<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.
Use the `invoke_subagent` with `invoke_subagent` with agent `cf-writer-deep` and include this write spec:
```
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:
```markdown
---
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** (pro) — never cf-writer (flash). 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