paper-code-tutorial

name	paper-code-tutorial
description	Use when the user wants to convert a research paper + its reference code (or any code repository) into a layered, visualized, chapter-based bilingual web tutorial in the style of shareAI-lab/learn-claude-code — producing Markdown chapters plus a Next.js site with interactive SVG visualizations, per-chapter source viewer, simulated execution trace, and design-decision deep dives.

Paper + Code → Tutorial

Overview

Turns a paper.{pdf,md} + code/ pair (placed in the working repo) into a monotonically layered, multi-modal tutorial: every chapter adds exactly one mechanism on top of the previous chapter, told four ways at once — Markdown prose, ASCII diagram, animated SVG, runnable source.

Core principle (from learn-claude-code): constraint creates clarity. A ~120-line chapter ceiling, a fixed 6-section template, and a forced "what changed vs. previous chapter" diff table push the author to compress until only the essential mechanism remains.

Output per run:

• docs/zh/sNN-*.md + docs/en/sNN-*.md — bilingual Markdown chapters
• web/ — Next.js 16 / React 19 / Tailwind 4 site, mirroring learn-claude-code's chapter-page composition (Hero Viz + 4 Tabs)
• web/src/data/annotations/sNN.json, scenarios/sNN.json — structured per-chapter data
• web/src/components/visualizations/sNN-*.tsx — one stepped SVG component per chapter

When to Use

• User puts a paper (PDF / markdown) and its reference implementation in a repo and says "做成教程" / "convert this to a tutorial" / "explain this paper with code"
• User references this skill by name, mentions learn-claude-code style, or asks for "可视化分章节的教程"
• User wants both static Markdown AND an interactive web app from the same source
• NOT for: standalone API docs (use writer/document-specialist), single blog posts, or content without paired runnable code

The Five-Layer Pedagogy

Every chapter produces five aligned artifacts. They must tell the same story at different fidelity levels.

Layer	Artifact	Length	Reader experience
1. Source	Layered reference impl (code/sNN_*)	Real LoC	"I can run it."
2. Prose	MD chapter (docs/{zh,en}/sNN-*.md)	≤140 lines	"I understand why and how."
3. Diagram	ASCII block inside MD + animated SVG component	1 figure each	"I see the shape."
4. Decisions	annotations/sNN.json (design choices + alternatives, bilingual)	3-5 entries	"I know why not the alternative."
5. Trace	scenarios/sNN.json (step-by-step simulated run)	6-12 steps	"I see it execute."

If any one layer is missing, the chapter is not done.

Workflow

Phase 0 — Discover & confirm

1. Scan the working repo for: paper.pdf / paper.md / papers/, and a code directory (code/, src/, impl/, or git submodule).
2. If multiple papers → ask which one. If no clear code → ask user to point to entry file.
3. Read the paper (chunked, ≤20 pages per Read call for PDFs).
4. Sketch a chapter plan (see references/chapters-plan-schema.yaml) and confirm with user before generating.

Phase 1 — Chapter plan

Produce plan/chapters.yaml with:

• 6-14 chapters, each adds ONE mechanism
• Each chapter mapped to: paper sections, code files/symbols, the new concept introduced, the diff vs. previous chapter, the visual idea
• Grouped into 3-5 thematic layers (e.g. Tools / Planning / Memory / Concurrency / Collaboration in learn-claude-code; for a paper this might be: Foundations / Architecture / Training / Inference / Applications)

Stop here. Ask user to approve the plan before continuing. See references/chapters-plan-schema.yaml.

Phase 2 — Generate chapters (parallel)

For each chapter, dispatch a subagent that produces all 5 artifacts using the strict templates:

• Use references/chapter-template-zh.md verbatim for the MD structure (problem → solution → how it works → diff table → try it)
• Use references/chapter-template-en.md for the English mirror — translate semantically, not word-for-word
• Generate the annotations (references/annotations-schema.json) — 3-5 design decisions, each with title/description/alternatives, all bilingual
• Generate the scenario (references/scenarios-schema.json) — a realistic step-by-step trace through the chapter's mechanism
• Generate the visualization (references/visualization-template.tsx) — stepped SVG with active nodes/edges per step

Run these in parallel via subagents when chapters are independent. See references/parallel-generation.md.

After each chapter is generated: dispatch a code-reviewer agent (Gate G1). If findings, dispatch a fix agent, re-review, then continue. See references/review-workflow.md.

After each phase / round of parallel agents: dispatch a critic agent (Gate G2) to verify cross-chapter consistency (diff chain, terminology, references). Fix in-band before next phase. See references/review-workflow.md.

Phase 3 — Web scaffold

If web/ does not exist, scaffold from the snippets in references/scaffold-snippets/:

• package.json, tsconfig.json, next.config.ts (always set output: "export" so the build produces a static out/ deployable to any host), tailwind setup
• .github/workflows/deploy.yml — default deployment target is GitHub Pages (free, no third-party account, only needs a Settings toggle). Vercel / Cloudflare Pages also work without code changes because the build is static. See references/web-scaffold.md § Deployment.
• src/app/[locale]/[version]/page.tsx + client.tsx (server + interactive tabs)
• src/app/[locale]/layers/page.tsx (cross-cutting layer index)
• src/components/docs/doc-renderer.tsx (unified + remark + rehype pipeline)
• src/components/code/source-viewer.tsx (line-numbered + syntax highlight)
• src/components/visualizations/index.tsx (lazy-loaded per-chapter SVG)
• src/lib/constants.ts — regenerate from plan/chapters.yaml (VERSION_META, LAYERS, LEARNING_PATH)
• scripts/extract-content.ts — adapt to the paper's code language (Python/JS/Rust/etc.); parses source + MD into src/data/generated/{versions,docs}.json at build time
• i18n strings (src/i18n/{zh,en}.ts)

Phase 4 — Verify

1. cd web && npm install
2. npm run dev — open each chapter route, check MD renders, viz animates, source loads, tabs work
3. npm run build — ensure static export succeeds
4. Use the verify skill / superpowers:verification-before-completion — do not claim done without seeing each chapter page render

Phase 4.5 — Final review (Gate G3)

Before declaring done, dispatch a critic (Opus) agent for end-to-end review of the whole deliverable. See references/review-workflow.md § G3. Block hand-off until the reviewer returns "TUTORIAL READY FOR DELIVERY".

Phase 5 — Hand-off

Report: chapter count, total LoC, web URL, any chapters needing manual touch-up on the visualization (SVG often needs human eye).

Quality bars (non-negotiable)

Rule	Why
Code snippets in MD must be copy-paste identical to the source file	Reader trust; future drift detection
Every chapter must have a diff-vs-previous table	Forces monotonic-additive design
Every chapter must have a "试一试"/"Try it" with runnable commands	Verification path for the reader
ASCII diagram comes before SVG	ASCII works in cat/git, SVG only in browser
Annotations must include alternatives field	Captures rejected designs — the most valuable knowledge
Chapter MD line count ≤140	Forces compression to the essential mechanism
Chinese is primary, English is mirror	Per user spec; check zh first when missing

Common mistakes

Mistake	Fix
Trying to cover whole paper in one mega-chapter	Slice by mechanism added, not by paper section
MD code drift from source	Code blocks must be excerpts (copy-paste); use // from src/X.py:L40-L52 comment
SVG visualization that just re-draws the ASCII	SVG must show temporal progression (active nodes per step), not be a static rendering
English written first, Chinese translated literally	Write Chinese first when Chinese is primary; English is a parallel translation, not a derivative
Scaffolding web/ from scratch every run	Idempotent: if web/ exists, only patch constants.ts + add new chapter files
Skipping Phase 0 confirmation	The chapter plan is the single most important decision; never auto-execute
Leaving unused locales (e.g. ja) wired after copying scaffold	Clicking the switcher 404s. Delete the locale at EVERY layer — see references/web-scaffold.md § "No unused locales remain wired".
Locale switcher uses window.location.href = newPath without basePath	Breaks on GitHub Pages (/repo/en/s07 → /zh/s07 → 404). Prepend process.env.NEXT_PUBLIC_BASE_PATH — see references/web-scaffold.md § "Known-gotcha".
Default locale forced to English even when paper is primarily Chinese	Edit app/page.tsx redirect target + i18n fallbacks. Don't ship the upstream redirect("/en/") unchanged.

References (load on demand)

• references/methodology.md — deeper analysis of why this pattern works (incremental layering, multimodal redundancy, source-anchored prose)
• references/chapter-template-zh.md — strict Chinese MD template
• references/chapter-template-en.md — English mirror template
• references/chapters-plan-schema.yaml — Phase 1 plan format
• references/annotations-schema.json — design decisions schema
• references/scenarios-schema.json — simulated trace schema
• references/visualization-template.tsx — stepped SVG React component
• references/web-scaffold.md — Next.js scaffold file-by-file + GitHub Pages deployment
• references/parallel-generation.md — how to dispatch per-chapter subagents
• references/review-workflow.md — three-gate review pattern (G1 per-chapter, G2 per-phase, G3 final delivery)

Red flags (STOP and ask)

• About to generate chapters without user-approved plan → STOP, present plan first
• About to fabricate code that isn't in the source → STOP, every snippet must trace to a file:line
• About to skip the diff table because "this chapter is a fresh start" → STOP, the first chapter says "before: nothing"; every subsequent chapter compares to the previous
• About to write the SVG visualization before settling the ASCII diagram → STOP, ASCII first, SVG is the same diagram with motion
• Chapter MD exceeds 140 lines → cut, don't extend; the constraint is the point

Bottom line

This skill does not invent pedagogy — it imposes the learn-claude-code pattern. Faithfulness to the constraint (5 layers per chapter, monotonic additivity, diff tables, line-count ceiling) is what makes the output good. When in doubt, go re-read a learn-claude-code chapter (e.g. s01-the-agent-loop.md) and copy the rhythm.