build-study-guide
/build-study-guide
Review a codebase and generate layered, evidence-cited onboarding docs (overview, per-layer, gotchas, how-to-build, how-to-run-and-debug) under docs/onboarding/. Use when the user wants to onboard to or document an unfamiliar repo, or runs /tutor:build-study-guide.
- Author
- patmagee ↗
- Repository
- tutor ↗
- Licence
- Apache-2.0
- Last repository change
- 10.06.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 10.06.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Review a codebase and generate layered, evidence-cited onboarding docs (overview, per-layer, gotchas, how-to-build, how-to-run-and-debug) under docs/onboarding/. Use when the user wants to onboard to or document an unfamiliar repo, or runs /tutor:build-study-guide.
Arguments
/build-study-guide [path] [--perspective structure|data-flow|security|use-cases|gotchas|comprehensive] [--axis service|component|feature|la
Original author description
Review a codebase and generate layered, evidence-cited onboarding docs (overview, per-layer, gotchas, how-to-build, how-to-run-and-debug) under docs/onboarding/. Use when the user wants to onboard to or document an unfamiliar repo, or runs /tutor:build-study-guide.
How it works
- Inputs
- Procedure
- Refresh (--refresh)
- Drive-to-code rule
- See also
SKILL.md preview
---
name: build-study-guide
description: Review a codebase and generate layered, evidence-cited onboarding docs (overview, per-layer, gotchas, how-to-build, how-to-run-and-debug) under docs/onboarding/. Use when the user wants to onboard to or document an unfamiliar repo, or runs /tutor:build-study-guide.
user-invocable: true
disable-model-invocation: true
argument-hint: "[path] [--perspective structure|data-flow|security|use-cases|gotchas|comprehensive] [--axis service|component|feature|layer] [--refresh]"
---
# /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.
Versions
The database has no other skills named build-study-guide.
Database snapshot: 13.11.2026 · package version 2835b67213a5 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 1 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100onboarding
Generate or regenerate ONBOARDING.md to help new contributors understand a codebase. Use when the user asks to 'create onboarding docs', 'generate ONBOARDING.md', 'document this project for new developers', 'write onboarding documentation', 'vonboard', 'vonboarding', 'prepare… - 100onboarding
Generate or regenerate ONBOARDING.md to help new contributors understand a codebase. Use when the user asks to 'create onboarding docs', 'generate ONBOARDING.md', 'document this project for new developers', 'write onboarding documentation', 'vonboard', 'vonboarding', 'prepare… - 100onboarding
Generate or regenerate ONBOARDING.md to help new contributors understand a codebase. Use when the user asks to 'create onboarding docs', 'generate ONBOARDING.md', 'document this project for new developers', 'write onboarding documentation', 'vonboard', 'vonboarding', 'prepare… - 100onboard
Instant Project Onboarding — generate a complete onboarding guide for any project. Use when user wants to onboard a new developer, understand a new codebase, or generate project documentation. - 90codebase-onboarding
Use when joining a project or receiving a task in an unfamiliar codebase. Build a navigable map of an unfamiliar repository before proposing edits. Do not use when the task is unrelated to existing project code. - 90study
Interactive, guided code walk through generated onboarding docs — one layer at a time or by a route you choose (e.g. start at the database, follow a request). Three study modes — guided (drive-to-code, default), lecture (dense, optional questions), reference (dense, no…