Learn from project

Learn from a project → own it

Why this exists

People now ship real projects that an AI wrote for them — faster than they can understand the code. It runs, but they can't explain how, can't tell if it's reliable, and can't safely change it. That's fragile ownership. This skill turns "the AI made this" into "this is mine": it reads the project the way a patient senior would walk a teammate through it, and leaves behind a document that lets the person explain it, trust it, and extend it.

The reader may not be a deep engineer — so concrete engineering is explained, not assumed. When the code calls a library or API, say which one, what it's for in general, and what this specific call does here. When it uses a higher concept (causal intervention, a statistical test), name it and explain it. Both layers matter: the stack (how it's built) and the ideas (why it works).

What "owning it" means (the bar to clear)

By the end, the person should be able to, without looking:

• say what the project does and how it's structured;
• point to where the important logic lives and explain how it works;
• name the main libraries/APIs/concepts it uses and what each is for;
• say which results to trust and which are shaky.

Write toward that bar. The output is a learning artifact, not an audit report — correctness checking is included only as the "can I trust this?" part.

The method (4 steps, top-down)

The code is the main object. A paper/report/README is helpful context — read it if it exists, but don't depend on one.

Step 1 — What is it & what does it do

One plain paragraph: what the project is for, what it produces, who/what runs it. Get this from the README/paper if present, else infer it from the entry points and outputs. No jargon the reader wouldn't know.

Step 2 — Map the code structure

A quick map so they can navigate: the directories/modules and what each is for (a small tree or table). Then list the experiments/runs/entry points and what each one is for. This is the lay of the land before any close reading.

Step 3 — Read the code in run order (the core of the skill)

Follow the actual execution / data flow, not the alphabet: entry point → inputs/data → core transforms → run → outputs. Generate a fresh reading itinerary in that order each time.

Split every file into core vs environment, because attention is finite and most files don't deserve close reading:

The test: If this code had a subtle bug, would a result/output change, or would the program just crash, slow down, or look ugly? Output changes → 🔴 core (read closely — the real logic lives here). Crash/slow/cosmetic → ⚪ environment (skim: confirm inputs/outputs, move on).

	🔴 core (read closely)	⚪ environment (skim)
what it is	the logic that decides the result	the plumbing that makes it run
typical	the main algorithm/transform; the metric & statistics; how data/inputs are built; the key decision/output logic	arg parsing, config, logging; job/SLURM scripts; paths, caching, device setup; data IO & loaders; install/deps

For each 🔴 core file, give the reader four things — this is the payoff:

1. What it does — its job in one line.
2. How it works — the implementation logic in plain language, step by step ("it loads X, then for each item does Y, then computes Z"). Walk the actual control flow of the important function(s), not a vague summary.
3. Stack used here — the concrete engineering, each named and explained for a non-expert: which library (e.g. numpy, transformers, pandas), which API/call (e.g. AutoModel.from_pretrained, np.random.choice), which language feature/pattern (e.g. list comprehension, decorator, dataclass) — what it is in general, and what it's doing here.
4. Concepts it embodies — the higher ideas (e.g. causal intervention, bootstrap CI), pointing to §5.

Environment files get one line each, grouped — no deep read.

Step 4 — Does it actually work? (trust)

Light, just enough to trust what you learned and rely on the project:

• Reconcile: do the numbers/outputs claimed (README, paper, comments) match what the code/result files actually produce? Open one and check.
• Backing & honesty: does every claim have something real behind it? Flag anything overstated, hardcoded, faked, or shaky. The reader needs to know which parts to trust.

Output template

Produce one markdown document (offer to save it, e.g. LEARNING.md in the project). Adapt depth to the project, but keep this shape:

# Owning <project name>

## 1. What it is & does
<one plain paragraph: purpose + what it produces>

## 2. Code structure
<tree or table: each dir/module → what it's for>
<entry points / experiments → what each is for>

## 3. How it works — reading itinerary (run order)
1. 🔴 `path/file.py` — <what it does>
   - how it works: <plain-language logic walkthrough>
   - stack here: `library` / `api_call()` / <language feature> — <each explained>
   - concepts: <link to §5>
2. ⚪ `path/plumbing.py` — <role> (skim)
...
> Spend your time on: <the 2–3 真 core files>

## 4. Does it actually work?
- reconcile: <claimed number/output ↔ what the code produces>
- trust: <what's solid vs shaky / overstated / hardcoded>

## 5. Knowledge points (what you now know)
### Concepts (domain + method)
- **Name** — what it is · why used here · `file:func` · go deeper: <pointer>
### Engineering & stack (libraries · APIs · language features)
- **`library` / `api()`** — what it is in general · what it does here · `file:line`
...

## 6. Own it: can you explain it?
<3–5 sentences the reader can now say about the project as if it's theirs —
the "elevator explanation". Then: the 1–3 gaps to close to fully own it.>

How to work

• Output language: write the document in English by default. If the user addresses you in another language (e.g. Chinese), write the whole document in that language instead — match the language of the user's request.
• Spend the reading budget on 🔴 core files. For ⚪ environment files, one line is enough. The goal is to teach where the ideas and the real logic are.
• Explain engineering at the right level: name the library/API/feature, say what it's for in general, and what this call does here. Assume the reader codes with AI but isn't a deep engineer — don't assume they know what from_pretrained or argparse or a list comprehension is; don't over-explain trivial syntax either.
• Keep concepts genuinely transferable: if a point only makes sense inside this repo, lift it to the general idea it instantiates.
• The "how it works" walkthrough is the heart for ownership — actually trace the logic of the key function, don't just restate its name.
• When asked for only part of this (e.g. "just the reading order", "just what libraries it uses"), produce that part well rather than forcing the whole template.

See references/worked-example.md for a filled-in example.