| name | study |
| description | Deeply learn a system that already exists — a codebase, an architecture, a primary source, or your own recent work — by reading the actual source in stages with a write→annotate→comment→quiz→score loop. Produces a durable study doc with retention built in. Use for onboarding, interview prep, primary-source mastery, or defending your own work. Distinct from /assess (snapshot our system) and /draft (design something new). Usually user-invoked; agent may suggest it when deep-learning intent appears. |
Study
The user typed /study <topic> — enter staged, source-grounded learning mode.
/study is for deeply learning something that already exists, with
retention. Where /assess snapshots our system to feed design and /draft
designs something new, /study learns — a codebase, an architecture, a body
of primary source, or your own recent work — by reading the actual source
and working through it in stages. The doc is a side effect; retention is the
product.
It formalizes the gather half of the gather→act cycle. Studies are durable
and citable: /assess and /draft may read a study as a source.
State dir convention: Always write to .meta/, creating it (and
subdirectories like study/) if needed. The study doc lives at
.meta/study/<topic>.md — but in the learner's study-home, which is
not always the target. Study-home ≠ study-target: the doc lives in the
learner's own workspace and the source anchors point outward at the target.
When the learner controls the target, home and target coincide (the common
case); when the target is shared/external/read-only, home is a separate repo.
Resolve this at Step 1.
The artifact structure is specified in references/study-format.md — read
it if you need the canonical shape. Scaffold from templates/study-doc.md.
Step 1: Goal + target gate
Capture three things before reading anything:
- Target — the source set: repo URL, local path, a paper, our own
code+test-logs. If it's missing, ask. Everything downstream is grounded in
real source, so there must be a source.
- Study-home — where the doc gets written. Default to the target's own
.meta/study/ when the learner controls the target. But if the target is
shared, external, or read-only (a take-home shared with reviewers, a
company's OSS for interview prep, a paper, a vendored dep), the trail must not
live there — prompt for / create a separate study home (a dedicated study
project or personal workspace) and record a Target repo: line in the
header (Step 3). Exemplar: honcho-internals.md lived in ~/Development/meta,
anchors pointing at the Honcho repo.
- Goal — free text: why we're learning ("interview prep for Plastic
Labs," "defend the take-home Monday," "understand pgvector indexing"). The
goal frames quiz difficulty and pacing.
- Mastery targets (optional) — the precise domains that must be understood
by the end, a minimum viable surface. Seed them from an external brief if
one is referenced (read it — e.g. a screening brief's "Final review" section
is a literal target list), gather/suggest them with the learner, or leave them
empty for open-ended general mastery. Record under
## Mastery Targets.
If the goal implies a deliverable beyond knowledge in the learner's head,
offer to set up a study product (see ## Study Products in the format ref):
a questions-for-interviewer list, a probe-answers sheet, a practical-advice
writeup. Pure-ingest studies ("this whitepaper is neat") skip it.
Step 2: Stage 0 (conditional) — source-gathering
Only if the topic has no pre-given source (an abstract subject like
"financial instruments for low-income families"):
- Propose candidate sources.
- Vet them with the learner as authoritative — don't proceed on sources the
learner hasn't blessed.
- Record the vetted set as the source anchors.
Skip this step entirely when the source is already given (a repo, a paper, our
own code). Don't manufacture a source-gathering pass where the source is obvious.
Step 3: Source anchors + stage map
Read enough of the source to lay out the study. Then write the doc header:
- What this is, in a sentence.
Target repo: — include this line only when study-home ≠ study-target
(Step 1): name the outward target the anchors point at, so a reader knows the
source lives elsewhere.- Source anchors — real file/dir paths or source refs, so every stage is
grounded.
- A one-paragraph description of the loop (so a reader knows how to use the doc).
- The goal.
## Mastery Targets / ## Study Products sections if Step 1 produced them.
Then write the stage map: numbered stages, one-line scope each, plus a
pacing note. Derive the stage count from the source (Honcho was 7 stages;
a reference architecture was 10 layers) — propose it, let the learner adjust.
Get the learner's sign-off on the stage breakdown before diving in. The map
is the contract for what we're about to study.
Step 4: The per-stage loop (the heart of the skill)
Strictly one stage at a time. Run this rhythm per stage:
- Write the stage — to-the-metal, citing real
file/function/table
names, verified against source. Append it under the stage's heading.
- Learner reads and annotates INLINE — their comments live next to the
prose they react to. Wait for them.
- Comment on the notes — affirm strengths specifically; correct
misconceptions precisely, with the mechanism; name the valuable misses
(a wrong answer that taught something worth the stumble).
- Craft a TARGETED quiz — probe the soft spots the notes exposed and the
mastery-target domains; skip what the learner clearly nailed. Post it as a
### Quiz block at the end of that stage. Do not pre-stage the quiz — it
must be informed by the notes that came back.
- Learner answers inline — preserve their raw answers; the trail is part of
the artifact's value.
- Score + log + unlock — proceed to Step 5.
Step 5: Score + log + unlock
After each quiz:
- Append a dated entry to the bottom
## Quiz Log: the question, the learner's
answer, a score (✓ / ✓ partial / ✗, flagging any ✗ that's a
valuable miss), and the correction/refinement with mechanism.
- Update the running Revisit weak-spots list. If a Revisit item proves
load-bearing, promote it to a mastery target — forward-only: it raises the
bar for remaining stages, it does not re-open an already-complete stage.
- Mark the stage done in the stage map, then unlock the next stage (back to
Step 4).
Step 6: Pacing + close
- Pace to the learner. One stage at a time, always. Respect "I'm hitting my
ingestion limit" — stop cleanly; the doc resumes next session (
/hello
surfaces in-progress studies).
- Completion is two orthogonal criteria: all stages studied and
minimum viable surface covered. A study with mastery targets stays open
(and may grow new stages) until both clear. A study without targets is
one-dimensional — done when stages are done.
- On completion, write a "study complete" marker in the stage map and
add/refresh the
study/index.md entry (scaffold from
templates/study-index.md). For a two-dimensional study, the index status
shows both subitems (stages complete? / surface covered?).
- The study doc is durable reference — not archived, not graduated. It lives
on as a permanent learning artifact that assessments and designs may cite.
Core principles (what makes it work — non-negotiable)
- Read the actual source. Grep/fetch real files; cite real symbols. Correct
marketing and abstraction with ground truth.
- Verify before you quiz or grade. Confirm a mechanism in source before
asserting it or building a question on it — never grade against a guess.
- Quiz after the notes, targeted at weakness. Redundant questions on
mastered material waste the loop.
- Inline annotation, learner's voice preserved. Never paraphrase the
learner's notes away.
- Strictly one stage at a time — a feature, not a limitation. Stages build
on each other, and one-at-a-time blocks passive skimming.
- Affirm + connect. Tie new mechanisms back to the learner's own prior
reasoning and adjacent knowledge — it cements retention and builds confidence.
