learning-report

name	learning-report
description	Write a teaching-grade, interactive learning report into ~/learning/ that distills what was worked on in the current conversation AND the related concepts behind it — both at full depth. Subagents author markdown in a typed-block convention (quiz and diagram code fences, skippable fenced divs, callout blockquotes, front-matter metadata); a bundled pandoc converter renders each file into a self-contained interactive HTML page with a TOC, validated multiple-choice quizzes with per-option feedback, HTML diagrams, and a computed reading-time footer. Splits a large or multi-concept report into a directory of numbered pieces with an index. Use when the user says "/learning-report", "write a learning report", "document what we learned", "turn this into a learning doc", or asks to teach-back the session. An optional arg focuses the report on a specific topic.
model	opus

learning-report — teach-back the session into ~/learning/

Produce a learning report that a capable-but-inexperienced reader can learn from end to end. The report covers two halves at equal depth:

1. The conversation — what was actually built, debugged, or decided in this session.
2. The related concepts — the named ideas, patterns, trade-offs, and theory behind that work.

Neither half is a footnote to the other. A deep core with shallow tangents is a failure mode. Go as deep on the surrounding concepts as on the concrete work.

Exhaustiveness directive (read first)

While running this skill, do not economize on tokens or context. Do not truncate, do not summarize to save room, do not stop at "good enough." Favor completeness over brevity. The architecture below exists precisely so that report length is never bounded by any single context window — large reports are expected, and the directory-split form handles them.

Division of labor — markdown in, HTML out

Agents author markdown in the convention below; the bundled converter (converter/convert.sh, pandoc + Lua filter) renders each .md into a self-contained interactive HTML page. Agents never write page HTML, CSS, or scripts — the LLM owns semantics, the toolchain owns syntax. The converter also validates: a malformed quiz or diagram fence fails the conversion loudly, and the authoring agent must fix its markdown.

Both files are kept: the .md is the canonical, greppable source; the .html is a build artifact, never hand-edited, re-renderable at any time.

Sourcing — the conversation, then the code around it

• Primary source: the current conversation — the work, decisions, errors, and fixes.
• Broadly explore the surrounding code. Do not limit background material to what was said aloud in the session. Read the code around the touched files (LSP/fff/Read) to explain the existing system the work landed in: the callers, the data model, the config, the deploy path. Context that is one Read away belongs in the Background section even if the conversation never mentioned it. Do this exploration during outlining, and pass the findings to subagents as source material.

Architecture — never hold the whole report in one context

The orchestrator (you, in the main loop) plans, renders, and assembles but does not write the prose of every piece inline.

1. Resolve the topic. Source = the current conversation. If an arg was given, focus the report on that topic (still grounded in this session's work). Identify (a) the concrete work done, (b) the related concepts worth teaching, and (c) the surrounding-code background (explore now).
2. Outline. Draft a piece list — section titles + a one-line scope each. Decide single-file vs directory (rule below). Choose the report's diagram families so all pieces draw the same kinds of pictures.
3. Fan out. Spawn one Agent subagent per piece (use the Agent tool, default general-purpose/claude type). Each subagent writes its own .md file directly to disk and returns only a short confirmation (path + one-line summary) — not the prose. Launch independent subagents in a single message so they run concurrently. Pass each subagent: the style checklist, the authoring convention, its assigned scope, the relevant facts/code from the conversation and code exploration, the chosen diagram families, exact sibling filenames for links, and the exhaustiveness directive.
4. Assemble the index (directory form only) — you write index.md yourself from the subagents' one-line summaries; you never need their full text for this.
5. Render. Run the converter on the new file or directory: ~/.claude/skills/learning-report/converter/convert.sh <path>. If a file fails (the filter names the offending quiz/diagram), fix that .md — or send it back to its subagent — and re-run. The converter is the syntactic gate; do not hand-verify what it already enforces.
6. Verify content, then report back. Confirm an .html exists next to every .md and the index links resolve; then give the user the path(s) and a short outline.

For a small single-concept report you may write the one .md inline instead of fanning out — but the moment it is multi-piece, delegate each piece. Rendering is always yours.

Target

• Write to ~/learning/. Run mkdir -p ~/learning first (it may not exist).
• Date-prefix every top-level name with today's date so reports sort chronologically and never collide: YYYY-MM-DD-<slug>.md or YYYY-MM-DD-<slug>/.
• ~/learning/ is output, not config — never add it to install.sh or symlink it. Only this skill folder (under dotfiles/claude/skills/) is tracked configuration.

Single-file vs directory — the split rule

Split into a directory when either holds:

• Decomposition: the topic breaks into 3+ distinct sub-topics that each deserve their own deep treatment (e.g. a 5-concept series). This is the primary trigger — a single long investigation (one narrative) stays one file even at 90 KB; a series of concepts becomes a directory.
• Growth: the report is outgrowing one readable page (rough guide: past ~1,500 lines / many screens of scrolling).

Forms:

• Single file: ~/learning/YYYY-MM-DD-<slug>.md
• Directory (preferred when splitting): ~/learning/YYYY-MM-DD-<slug>/ containing index.md plus numbered pieces 01-<piece-slug>.md, 02-<piece-slug>.md, …

<slug> is kebab-case derived from the topic. Language of the report follows the language of the conversation/topic (do not hardcode Korean or English).

Report structure (every report file)

The pedagogical arc from context to self-test. The converter adds the TOC and footer — do not author them.

1. Front matter (YAML) — see the authoring convention.
2. Hook — open with a question, an analogy, or the concrete problem from the session. Not a definition.
3. Background — layered. First a deep background for beginners inside a ::: skippable div (its summary= says who can skip it); then a narrow background directly relevant to this session's work, as normal prose. Assume nothing about how much the reader already knows.
4. Intuition. The core essence before any real code: concrete worked examples with toy data (small invented values traced end to end), diagram fences liberally. Essence, not full details.
5. The work. A high-level walkthrough of what was actually done this session — real file names, code, commands — grouped and ordered understandably, not chronologically.
6. Related concepts. The named ideas, patterns, and theory behind the work, at full depth.
7. When the other choice is fine. Honest trade-offs — no idea is universally best. A small table works well here.
8. Quiz. One or more quiz fences, spec in the convention.
9. Lesson. Bullet recap + a bold "One line to remember:".
10. Glossary (single-file reports and the index) — term / plain-meaning table.

Authoring convention (give this verbatim to every subagent)

Plain GFM markdown (headings, tables, fenced code) plus these typed blocks. Leaf data rides in code fences; markdown-bearing containers ride in fenced divs. The converter validates and fails loudly on malformed blocks — fix the markdown, never work around it.

Front matter — opens every file:

---
title: {Report title}
difficulty: {Beginner → Intermediate, etc.}
prerequisites: {what the reader must already know}
next: 02-{slug}.html    # series pieces only — exact sibling filename, .html
index: index.html       # series pieces only
---

Reading time is computed by the converter; never author it. The footer and series navigation are rendered from this metadata.

Quiz — a ```quiz fence. Q: opens a question; * opens an option; *= marks the single correct option; indented ! lines attach that option's explanation. Write the correct option first — the converter cycles its final position automatically, so option positions and lengths must carry no tells only in wording, never by placement:

```quiz
Q: {Question — medium difficulty: answerable only if the substance was understood; no gotchas}
*= {Correct option}
   ! {Why it is right — one or two sentences}
*  {Wrong option, similar length and specificity}
   ! {Why it is wrong}
*  {Wrong option}
   ! {Why it is wrong}
*  {Wrong option}
   ! {Why it is wrong}

Q: {Next question…}
```

Counts: 5 questions for a single-file report; 3–5 per series piece, covering only that piece; none on an index. Four options per question. Every option gets a ! explanation.

Diagram — a ```diagram fence. caption: once (optional); each row: is a left-to-right flow. [text] = box, [(text)] = datastore box, "text" = floating label, -> = arrow. Always put example data in boxes and labels, not just component names:

```diagram
caption: Read path for plan 42
row: [Browser] -> "GET /plans/42" -> [nginx :443] -> [Spring :8080]
row: [PlanService] -> "SELECT … WHERE id=42" -> [(MySQL)]
```

If a diagram truly cannot decompose into rows (deep trees, grids), fall back to ASCII art in a plain code fence — rendered honestly as <pre>. Prefer the DSL.

Skippable background — a fenced div; the interior is normal markdown (paragraphs, lists, code blocks all fine):

::: {.skippable summary="New to ORMs? Start here"}
{deep beginner-level background…}
:::

Callout — a > blockquote is a key-insight callout; use for the report's most important sentences, key definitions, and edge cases.

Links — write relative links between pieces against the .md filenames (they work in editors); the converter rewrites them to .html. Absolute URLs pass through untouched. Never reference external scripts, styles, or images — pages must stay self-contained.

Style checklist (give this verbatim to every subagent)

• Write with the clarity and flow of Martin Kleppmann — engaging, classic style, smooth transitions between sections. The items below are local features; this voice is the global one that makes them cohere.
• Idiomatic essayist register, idioms glossed at the foot. Beyond clarity, carry the idiom, dry understatement, and cultural/technical reference of a sharp technical essayist — the reader is training to read Hacker News and lobste.rs. Do not explain idioms inline; collect the hard ones in a short Idioms list at the very bottom of the piece (one line each), so the reader infers first and checks after. This is separate from naming concepts: technical terms are still defined inline on first use. Idiom must serve the explanation, never blur a concept.
• Open with a hook, not a definition.
• Layer the background: a skippable deep layer first, then the narrow layer.
• Name every concept explicitly. "This pattern is called colocation." "This is optimistic locking." Define each named term in one plain sentence the first time it appears.
• Build intuition with toy data before real code: small invented values traced end to end.
• Tie theory to the real work. Every abstract idea links back to what was actually done or decided this session, with the real file names, code, or commands.
• Use the reader's existing knowledge as anchors (CS-course ideas: transactions, coupling, graphs, Unix daemons) rather than assuming team/industry experience.
• Show, with artifacts: before/after code blocks, diagram fences, and trade-off tables. Reuse the report's chosen diagram families; put example data in every diagram.
• Call out key insights as blockquotes ("> The most important sentence in this report: …").
• Be honest about trade-offs — include a "when the other choice is fine" section.
• Quiz questions test understanding, not recall of exact phrasing; every option's ! line teaches something.
• End with a Lesson section: bullet recap + a bold "One line to remember:".
• Equal depth on conversation-derived material and related-concept material.

Index skeleton (directory form — you author index.md)

---
title: {Series Title}
difficulty: {Beginner → Advanced}
prerequisites: {what the reader must already know}
---

# {Series Title}

**Purpose:** {one line — what this series explains and why it exists}

## Why this matters
{The 1–2 problems this work/concept solves, stated concretely.}

## The pieces

### 1. [{Piece title}](01-{slug}.md)
**The big idea:** {one or two sentences}
**Key insight:** {one sentence}

### 2. [{Piece title}](02-{slug}.md)
…

## Suggested reading order
Read in order — each builds on the last.
- **If you only read one:** {which, and why}
- **The "wow" piece:** {which}

## Glossary
| Term | Plain meaning |
|------|---------------|
| **{term}** | {one sentence} |

Populate the "big idea" / "key insight" lines from each subagent's returned one-liners — you never need their full prose to assemble the index.

Subagent prompt template

You are writing ONE piece of a learning report as MARKDOWN in a strict authoring convention.
Write it directly to:
  {absolute_path}.md
Sibling files (for front-matter next/index and in-text links — use these exact names):
  {index.md, 01-…, 02-…}

## Your section
{section_title} — {one-line scope}

## Source material (from the session)
{the concrete work, decisions, code, file names, commands relevant to this section}

## Background from the surrounding code
{what the orchestrator's code exploration found — the existing system this work landed in}

## Related concepts to teach at full depth
{the named ideas/patterns/theory this section must explain — treat with the SAME depth as the
concrete work above; do not skim them}

## Diagram families for this report
{the 1–3 diagram kinds chosen for the whole report — reuse these, with example data}

## Authoring convention (follow exactly — malformed blocks fail the build)
{paste the Authoring convention verbatim}

## Style checklist (follow every point)
{paste the Style checklist verbatim}

## Rules
- Do not economize on tokens or context. Favor completeness; large is expected.
- Write the file with the Write tool. You write ONLY markdown — no HTML, CSS, or scripts.
- Return ONLY: the path + a one-sentence summary +, if part of a series, the suggested "big idea"
  and "key insight" lines for the index. Do NOT return the prose.

After writing

• Render with ~/.claude/skills/learning-report/converter/convert.sh <file-or-dir>; fix any loudly-failing .md and re-run until failed=0.
• List the file(s) created with paths, and offer xdg-open on the entry .html.
• Give a 3–5 line outline of what the report covers.
• Do not commit unless the user asks (~/learning/ is typically not even a git repo).