Teach This Repo

Use a real codebase in reverse for developer education. The agent navigates the repository, assesses the learner, builds a teaching plan grounded in the actual source, writes lessons with real code excerpts, answers questions interactively, and typesets any of it as a PDF.

This is the opposite of "read the README and hope for the best" — the repo becomes a structured textbook tailored to the reader.

Two tracks

Taught — a learner, a plan, lessons in sequence:

1. /assess-learner — interview the learner and save a profile.
2. /plan-curriculum — analyse the repo + profile and write a sequenced teaching plan.
3. /write-lesson <N> — materialise a lesson with source-grounded explanations, excerpts, and exercises.
4. /qa-mode — interactive Q&A grounded in the source (use anytime, including mid-curriculum).

Explained — no profile needed, documents that stand on their own:

• /explain-repo — how the whole system works, traced along one worked path.
• /analyse-file <path> — a close reading of a single file: every symbol, its edges, its sharp corners.
• /file-by-file — batch analysis in dependency order, plus a navigable index.

Both tracks render the same way:

• /to-pdf <file|kind|all|pack> — typeset PDF via Typst.

All markdown lands in teaching/. PDFs land in pdf/.

PDF output

Markdown is the source of truth; the PDF is a build artefact. The renderer understands the conventions the writing commands already emit, so the same file reads correctly on GitHub and typesets properly:

Markdown	PDF
Citation paragraph ending in `path:42-58` above a fence	Framed excerpt, caption strip, gutter numbered from line 42
> [!WARNING] / [!NOTE] / [!TIP] / [!EXERCISE]	Tinted callout
<details><summary>Answers</summary>	Unwrapped, label bolded
YAML frontmatter	Cover page, running header, TOC

Example:

From `src/ingest/handler.py:42-45`:

```python
def handle_upload(request: Request) -> Response:
    payload = request.json()
    doc = Document.from_payload(payload)
    return enqueue(doc)
```

Typst raw blocks do not soft-wrap — keep quoted lines under ~92 columns or the right edge is clipped.

You can also drive the renderer directly:

shared/build-pdf.sh teaching/lessons/03-ingest.md          # -> pdf/03-ingest.pdf
shared/build-pdf.sh teaching/explainer.md docs/how-it-works.pdf

Requirements

Tool	Needed for	Notes
Typst	PDF output	Developed against 0.14
pandoc 3.x	markdown → Typst	Must have the Typst writer: pandoc --list-output-formats | grep typst
IBM Plex Sans / Mono	typography	Optional — falls back to system faces

Everything except the PDF commands works without either.

Styling

shared/teaching-styles.typ holds the palette, the document wrapper, and the code-excerpt / callout / check-understanding helpers. Change the palette there and every output follows. It is a standalone Typst module — you can import it from your own .typ files.

Skills

• repo-teacher — auto-invoked when the user says things like "teach me this repo", "explain how this codebase works", or "make a PDF explaining this". Orchestrates both tracks.

Design principles

• Source-grounded. Every code claim cites file paths and line ranges and uses real excerpts from the repo.
• Profile-calibrated. Lessons don't over-explain things the learner already knows, and don't hand-wave things they don't.
• Time-bounded. A finished short curriculum beats an abandoned long one.
• Honest about unknowns. If the code is unclear, the document says so rather than confabulating. If a design decision has no recorded reason, that is what gets written.
• Exposition, not review. Sharp edges get flagged where they'd mislead a reader; code style doesn't get graded.

Installation

/plugin install teach-this-repo@danielrosehill

License

MIT