{
  "markdown": "<p align=\"center\"><img src=\"logo.png\" width=\"120\" alt=\"logo\" /></p>\n\n# learn-codebase\n\n> *a collection of Claude Code skills for understanding code another agent (human or AI) has written*\n\nThis repo bundles paired skills that cover the two complementary halves of grokking an unfamiliar codebase:\n\n| Skill | Direction | What it produces | When to reach for it |\n|---|---|---|---|\n| [`learn-codebase`](./skills/learn-codebase/) | code → understanding | intent-anchored reading artifacts (Map / Walk / Probe / Master) with a Feynman-style plain-speech gate on every output | \"I need to grok feature X before I touch it\" |\n| [`quiz-codebase`](./skills/quiz-codebase/) | understanding → verification | Socratic questions with a 3-rung hint ladder; the answer is never revealed before attempt 4 | \"I think I get it — prove it to me\" |\n\n> **Code without intent = ritual mimicry.**\n> **Intent without code = aspiration.**\n> **Side-by-side = bidirectional traceability you can act on.**\n> **Being told ≠ understanding. The quiz is the gate.**\n\n---\n\n## The two skills, side by side\n\n### `skills/learn-codebase/` — intent-anchored reading\n\nReads a feature in **4 progressive levels**, stopping at the depth your task actually needs:\n\n| Level | Budget | Goal | Artifact |\n|---|---|---|---|\n| **1 — Map** | ≤5 min | What is this & why does it exist? | 3-line summary + one entry function |\n| **2 — Walk** | ≤30 min | How does the happy path flow? | Side-by-side trace table |\n| **3 — Probe** | ≤2 hr | Why is it built this way? | Decision matrix with rejected alternatives |\n| **4 — Master** | Deep | What invariants hold it together? | Invariant + seam map |\n\nEvery artifact pairs an intent quote (from spec / ADR / contract / test) with the matching code (`file:line`) **and** a plain-language one-liner anyone outside the project can follow. If a cell is empty, that's a probe target — not a problem.\n\nSee [`skills/learn-codebase/SKILL.md`](./skills/learn-codebase/SKILL.md).\n\n### `skills/quiz-codebase/` — Socratic verification\n\nThe inverse of learn-codebase. The agent becomes an **examiner**, not a tutor:\n\n- For every question, attempts **1, 2, 3** earn hints only — never the answer.\n- Attempt **4** reveals the full answer with a 2-sentence \"why\" and a follow-up probe.\n- The hint ladder (Orient → Narrow → Scaffold → Reveal) is non-negotiable; skipping rungs destroys the learning signal.\n\nQuestion types mirror learn-codebase Levels (Map / Walk / Probe / Master), with bias toward Level 2–3 because that's where useful gaps live.\n\nSee [`skills/quiz-codebase/SKILL.md`](./skills/quiz-codebase/SKILL.md).\n\n### Pairing them\n\nThe intended loop:\n\n1. Run `learn-codebase` to read the feature.\n2. Run `quiz-codebase` against the *same* feature 24 hours later (or before a PR review) to surface what didn't stick.\n3. Use the quiz's closing gap report as your re-read list for `learn-codebase`.\n\n---\n\n## Install\n\n### As Claude Code skills\n\nBoth skills live as sibling directories under `skills/`. Install whichever you need — they're independent.\n\n```bash\n# clone the repo once, somewhere you'll keep it\ngit clone https://github.com/cskwork/learn-codebase ~/code/learn-codebase\n\n# symlink each skill into Claude Code's skill directory\nln -s ~/code/learn-codebase/skills/learn-codebase ~/.claude/skills/learn-codebase\nln -s ~/code/learn-codebase/skills/quiz-codebase ~/.claude/skills/quiz-codebase\n```\n\nTo pick up upstream updates:\n\n```bash\ncd ~/code/learn-codebase && git pull\n```\n\nBoth symlinked skills pick up the new version automatically — no re-install needed.\n\nThen in any Claude Code session, ask:\n\n> \"Use `learn-codebase` to walk me through feature X.\"\n>\n> \"Quiz me on feature X with `quiz-codebase`.\"\n\nOr invoke either skill explicitly with the `Skill` tool.\n\n### As a human technique (no Claude Code required)\n\nRead [`skills/learn-codebase/SKILL.md`](./skills/learn-codebase/SKILL.md) for the reading method.\nRead [`skills/quiz-codebase/SKILL.md`](./skills/quiz-codebase/SKILL.md) for the self-testing method.\nOpen the templates under each skill's `templates/` folder. Follow the workflow. Stop when your task is done.\n\n---\n\n## Repository layout\n\n```\nlearn-codebase/\n├── README.md                                 # You are here\n├── LICENSE\n├── .gitignore\n└── skills/\n    ├── learn-codebase/\n    │   ├── SKILL.md                          # The reading skill itself\n    │   ├── templates/\n    │   │   ├── plain-speech-checklist.md     # Mandatory Feynman-style output gate\n    │   │   ├── sidebyside.md                 # The walk-table format\n    │   │   └── progression-checklist.md      # Per-level checklist\n    │   ├── examples/\n    │   │   └── twin-question-platform.md     # Levels 1-3 applied to a real spec\n    │   └── references/\n    │       ├── finding-intent.md             # Where to look first (forward + reverse)\n    │       └── diagnostic.md                 # Intent ↔ code drift self-audit\n    └── quiz-codebase/\n        ├── SKILL.md                          # The Socratic quizzing skill\n        └── templates/\n            ├── hint-ladder.md                # Pre-draft worksheet (mandatory)\n            └── quiz-ledger.md                # Per-session log + gap report\n```\n\n---\n\n## Use cases\n\n- Joining an AI-assisted team mid-stream.\n- Reviewing AI-generated PRs against a written spec.\n- Teaching a junior dev one feature without overwhelming them.\n- Planning a refactor: knowing every test that will turn red before you change anything.\n- Recovering intent from code when documentation has lapsed.\n- Verifying that a teammate (or yourself) actually grasped a feature before merging changes that depend on that grasp.\n\n---\n\n## Acknowledgements\n\nThe skills build on patterns from:\n\n- **Domain-Driven Design** — ubiquitous language and bounded contexts.\n- **Literate programming** — code paired with prose.\n- **Requirements traceability** (IBM DOORS lineage) — bidirectional mapping.\n- **Test-driven development** — tests as executable intent.\n- **Socratic method / Feynman technique** — knowledge proved by re-derivation, not recitation.\n- **Anthropic's skill-authoring guide** (`writing-skills`) — TDD applied to documentation.\n\n---\n\n## License\n\nMIT. See [`LICENSE`](./LICENSE).\n\n---\n\n## Contributing\n\nIssues and PRs welcome. If either skill fails on a real codebase you tried it on, that's the highest-value bug report — open an issue with:\n\n- which skill (`learn-codebase` or `quiz-codebase`),\n- the project type (mono-repo / split planning + code / etc.),\n- which level/attempt you got stuck at,\n- the missing piece in the skill or templates.\n\nThe skills' quality is measured by whether a fresh agent can apply them to a new codebase without prior context. Reports of failure on real codebases make them better.\n",
  "bytes": 6732,
  "sha": "c3cb1bf9e6c27f465f4d93442445161eb8559b932690487c621764369affe070",
  "repo_slug": "cskwork/learn-codebase",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_cskwork_learn_codebase_c314a782/readme"
}