build-study-guide

/tutor:build-study-guide

Produce living, evidence-based onboarding docs for a repo by reading the actual code, citing every claim, and writing a structured doc set under docs/onboarding/.

Inputs

Argument	Default	Notes
path	Current working directory	Repo root to analyze.
--perspective	comprehensive	Lens to emphasize: structure, data-flow, security, use-cases, gotchas, or comprehensive.
--axis	Auto-detected	Override the decomposition axis: service, component, feature, or layer. Skips detection; still confirm the layer list with the user.
--refresh	Off	Regenerate stale docs rather than doing a full rebuild. See Refresh below.

Procedure

1. Check for existing docs

Resolve the target repo root (from path, or cwd) and its docs/onboarding/ directory.

If docs/onboarding/index.md already exists and --refresh was NOT passed:

• Run the Freshness procedure defined in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md.
• Tell the user that docs already exist, show the freshness assessment, and offer /tutor:study instead of rebuilding.
• Only continue a full build if the user explicitly confirms they want to overwrite.

2. Detect the axis

Inspect build files (e.g. build.gradle, package.json, Makefile, pyproject.toml), module/package layout, and directory conventions to propose a decomposition axis (service | component | feature | layer) and a concrete, ordered layer breakdown.

Present the proposed axis and layer list to the user via AskUserQuestion and ask them to confirm or edit. If --axis was given, skip detection and go straight to confirming the layer list.

3. Pick the perspective

Unless --perspective was given, ask the user which lens to emphasize via AskUserQuestion:

• structure — component relationships and module boundaries
• data-flow — how data moves end-to-end
• security — trust boundaries, auth, secrets handling
• use-cases — key user journeys through the code
• gotchas — cross-cutting pitfalls and surprises
• comprehensive — all of the above (default)

4. Analyze thoroughly, citing as you go

For each confirmed layer, read the actual source files and capture:

• What the layer does and its responsibility boundary.
• How data enters, is transformed, and exits.
• Key use cases or request paths it serves.
• Gotchas: surprising behaviors, performance traps, ordering dependencies, misnamed abstractions.

For breadth, you MAY dispatch one subagent per layer to do mechanical reading; each subagent must return a cited topic list (file:line references, not prose summaries). Every claim must carry a file:line citation using the format defined in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md. If you cannot cite a claim, keep investigating until you can — or drop it.

5. Write the docs

Write the complete doc set exactly per the directory layout, index.md front-matter format, layer-doc structure, ## Topics section format, difficulty tags, and citation format defined in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md. Do not invent alternate formats.

Files to produce:

• docs/onboarding/index.md — front-matter with the CURRENT git rev-parse HEAD (short hash), branch, dirty state (true/false), today's date, the confirmed axis, and the chosen perspectives; followed by the linked layer table.
• docs/onboarding/00-overview.md — architecture overview, end-to-end data-flow, and the full layer map with brief per-layer descriptions.
• docs/onboarding/NN-<layer>.md — one file per layer (zero-padded order: 01, 02, …), each with a free-form overview section followed by a ## Topics section with ≥1 difficulty-tagged topic and ≥1 citation per topic.
• docs/onboarding/gotchas.md — cross-cutting pitfalls that span multiple layers or don't belong in a single layer doc.
• docs/onboarding/how-to-build.md — derived from README, build files, and CI configs. Every build step must be cited to the file where it appears.
• docs/onboarding/how-to-run-and-debug.md — derived from README, docker-compose, run configs, and CI. Cite each instruction to its source file.

Diagram generation

After drafting the overview prose and layer docs, decide whether to add diagrams, following the diagram spec in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md.

00-overview.md — always include a system-level ASCII diagram in the prose body (after the architecture summary, before any layer map table). Show each major component and the primary data-flow edges between them. Use the drawing conventions in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md.

Layer docs (NN-<layer>.md) — add a ## Diagram section only when ALL three hold:

1. The active --perspective is data-flow, security, or comprehensive.
2. The layer has meaningful spatial structure: a pipeline (data enters, is transformed, exits through a clear sequence of steps) OR a trust/security boundary that is not obvious from the topic names alone.
3. The resulting diagram fits ≤ 12 labelled components. If not, omit it and use prose.

Place the ## Diagram section between the overview prose and ## Topics. For security boundaries use a double-line box (╔═ zone ═╗) with untrusted callers shown outside pointing in. Use a plain fenced code block (no language tag) — never mermaid.

Do not add diagrams to gotchas.md, how-to-build.md, or how-to-run-and-debug.md.

For repos with no git history, still write the gitHash/gitBranch/gitDirty keys (the lint requires them) using placeholders — gitHash: none, gitBranch: none, gitDirty: false — and note in the overview that the repo is not under git. The Freshness procedure in ${CLAUDE_PLUGIN_ROOT}/references/conventions.md already handles the non-git case.

6. Self-check

Run the bundled lint script and fix every reported problem before finishing:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/lint_onboarding.py" <repo-root>

The script exits 0 when all conventions hold and every citation resolves to an existing file and line range; it exits 1 and prints each violation. Do not skip this step or report completion before the script exits 0.

7. Report

Tell the user:

• Which files were written and how many topics were captured per layer.
• The git hash the docs are pinned to.
• Any layers where coverage felt thin (citations were hard to find).
• Suggest /tutor:study to start learning from the generated docs.

Refresh (--refresh)

1. Run the Freshness procedure from ${CLAUDE_PLUGIN_ROOT}/references/conventions.md to determine which areas changed since gitHash.
2. Re-read and regenerate only the layer docs whose source areas changed (based on git diff --name-only <gitHash>..HEAD). Leave layer docs for unchanged areas and .tutor/progress.md untouched.
3. Rewrite index.md's gitHash, gitBranch, gitDirty, and generatedAt to reflect the current state.
4. Re-run the lint script (step 6 above) over the full doc set before finishing.

Drive-to-code rule

No uncited claims. A topic with zero citations is a bug. If you cannot point to a file:line, keep investigating until you can — or drop the claim entirely. This rule applies to every file in the doc set, including overview prose and the how-to docs. See ${CLAUDE_PLUGIN_ROOT}/references/conventions.md for the exact citation format and regex.

See also

• ${CLAUDE_PLUGIN_ROOT}/references/conventions.md — authoritative formats for index.md front-matter, layer docs, ## Topics structure, difficulty tags, citation syntax, .tutor/progress.md, the Freshness procedure, and the lint script.
• ${CLAUDE_PLUGIN_ROOT}/references/sample-repo/docs/onboarding/ — a worked example of the full target output.