codebase-onboarding

Name: codebase-onboarding
Author: neuromechanist

37stars7forks

How to install codebase-onboarding?

neuromechanist/research-skills/codebase-onboarding

$npx -y skills add neuromechanist/research-skills --skill codebase-onboarding

Installs into the current project.

Summary

Use this skill when the user asks to \"explore this codebase\", \"understand this repo\", \"map the architecture\", \"review our stack\", \"get up to speed\", \"break ground\" on an unfamiliar project or research field, \"what is the state of this project\", \"audit the architect

Files · 1

View on GitHub

SKILL.md

1	# Codebase and Field Onboarding
2
3	Build a verified map of an unfamiliar codebase, project, or research area
4	before planning or editing anything. The output is a reconnaissance report
5	that separates verified facts from assumptions, ending in a one-paragraph
6	diagnosis.
7
8	## The bootstrap sequence (run in this order)
9
10	1. Date and inventory. Run `date`. List the tree (source dirs, configs,
11	docs). Note the largest files with line counts; they are usually where the
12	complexity lives.
13	2. Intent docs before code. Read `AGENTS.md`/`CLAUDE.md`, `README`,
14	`.context/` (plan.md, research.md, decisions/), design docs. These say what
15	the project is SUPPOSED to be.
16	3. Code next. Read entry points, the main loop or route table, and the one
17	or two central types. Do not read everything; read what the intent docs
18	point at.
19	4. History. `git log --oneline -20`, open issues and PRs
20	(`gh issue list`, `gh pr list`). What was recently worked on, what is
21	planned, what is stuck.
22	5. What is ACTUALLY running. Processes, containers (`docker ps -a`), data
23	directories on disk, deployed endpoints, cron entries. This step
24	distinguishes "designed" from "operated": if the design exists in code and
25	issues but there is no runtime data on disk, the true next step is "turn it
26	on and calibrate", not "design more".
27	6. Verify the specific claim. Whatever question triggered this onboarding
28	("does compaction work?", "is the migration done?"): grep the source and
29	check live state for it directly. Absence of a script is not absence of
30	work; completed one-off scripts get deleted.
31	7. Probe third-party surfaces. Before planning against any SDK or API, run
32	one cheap introspection command against the INSTALLED version (import it,
33	list the dataclass fields, hit the version endpoint). Treat your
34	trained-in knowledge of library internals as a hypothesis.
35	8. Diagnose in one paragraph. State plainly what exists, what runs, what
36	is broken or missing, and what that implies, before proposing any action.
37
38	## Delegating exploration (2+ independent areas)
39
40	Split "where is X" (mechanical mapping, delegate it) from "what does X
41	actually say" (judgment docs such as ADRs and strategy docs; read those
42	yourself). When the area is larger than one context can hold:
43
44	Use the worker/intermediate tier for bounded scouts (Codex Luna/Terra or
45	Claude Sonnet), but keep diagnosis, keystone verification, and synthesis on
46	the lead tier (Codex Sol or Claude Fable/Opus). Close/remove each one-off scout
47	after its report is incorporated. See `agent-fanout` for escalation rules.
48
49	- Partition by architectural domain (backend / CLI / web / data / infra) with
50	disjoint file ownership, one read-only explorer per domain, all spawned in
51	parallel. Agent count = number of genuinely independent domains, within the
52	fan-out cap (see the agent-fanout skill).
53	- For a planned file decomposition: one explorer maps the target file's
54	internal structure (symbol inventory with line ranges, module-level mutable
55	state), a second maps external dependents (importers, test doubles, dynamic
56	imports), and a third reads the merged precedent of a prior similar change,
57	to mirror it.
58	- Every explorer prompt: numbered falsifiable questions naming the suspected
59	files/symbols, an explicit READ-ONLY instruction, and the output contract
60	"file:line references for load-bearing facts; conclusion-oriented; no file
61	dumps". Template in `references/exploration-prompts.md`.
62	- Re-verify the keystone fact yourself. Before any explorer conclusion
63	becomes a headline claim or a plan premise, spot-check the single most
64	load-bearing fact directly (one grep or file read). Explorer reports are
65	hypotheses with citations, not ground truth.
66
67	## Field / literature onboarding (research areas)
68
69	1. Run broad searches yourself first and save the raw corpus (queries and
70	results) to files; then delegate one summarizer per topic family with a
71	hard reading list, exact deliverable path, and a bounded return summary.
72	2. Prefer primary sources (specs, papers, official policy pages); use general
73	web search only as a fallback when a primary source is unreachable.
74	3. Record per-family findings in `research/<family>.md`, synthesize into one
75	survey doc, and record the resulting decision as an Architecture Decision
76	Record (ADR) with a dated log line in `.context/research.md`
77	("Problem, To investigate, Decision (date), Rationale").
78	4. If the project's own docs name a prefe

People who liked this also viewed

6 picks

Type

codebase-onboarding

37stars7forks

View on GitHub

How to install codebase-onboarding?

neuromechanist/research-skills/codebase-onboarding

$npx -y skills add neuromechanist/research-skills --skill codebase-onboarding

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Codebase and Field Onboarding
2
3	Build a verified map of an unfamiliar codebase, project, or research area
4	before planning or editing anything. The output is a reconnaissance report
5	that separates verified facts from assumptions, ending in a one-paragraph
6	diagnosis.
7
8	## The bootstrap sequence (run in this order)
9
10	1. Date and inventory. Run `date`. List the tree (source dirs, configs,
11	docs). Note the largest files with line counts; they are usually where the
12	complexity lives.
13	2. Intent docs before code. Read `AGENTS.md`/`CLAUDE.md`, `README`,
14	`.context/` (plan.md, research.md, decisions/), design docs. These say what
15	the project is SUPPOSED to be.
16	3. Code next. Read entry points, the main loop or route table, and the one
17	or two central types. Do not read everything; read what the intent docs
18	point at.
19	4. History. `git log --oneline -20`, open issues and PRs
20	(`gh issue list`, `gh pr list`). What was recently worked on, what is
21	planned, what is stuck.
22	5. What is ACTUALLY running. Processes, containers (`docker ps -a`), data
23	directories on disk, deployed endpoints, cron entries. This step
24	distinguishes "designed" from "operated": if the design exists in code and
25	issues but there is no runtime data on disk, the true next step is "turn it
26	on and calibrate", not "design more".
27	6. Verify the specific claim. Whatever question triggered this onboarding
28	("does compaction work?", "is the migration done?"): grep the source and
29	check live state for it directly. Absence of a script is not absence of
30	work; completed one-off scripts get deleted.
31	7. Probe third-party surfaces. Before planning against any SDK or API, run
32	one cheap introspection command against the INSTALLED version (import it,
33	list the dataclass fields, hit the version endpoint). Treat your
34	trained-in knowledge of library internals as a hypothesis.
35	8. Diagnose in one paragraph. State plainly what exists, what runs, what
36	is broken or missing, and what that implies, before proposing any action.
37
38	## Delegating exploration (2+ independent areas)
39
40	Split "where is X" (mechanical mapping, delegate it) from "what does X
41	actually say" (judgment docs such as ADRs and strategy docs; read those
42	yourself). When the area is larger than one context can hold:
43
44	Use the worker/intermediate tier for bounded scouts (Codex Luna/Terra or
45	Claude Sonnet), but keep diagnosis, keystone verification, and synthesis on
46	the lead tier (Codex Sol or Claude Fable/Opus). Close/remove each one-off scout
47	after its report is incorporated. See `agent-fanout` for escalation rules.
48
49	- Partition by architectural domain (backend / CLI / web / data / infra) with
50	disjoint file ownership, one read-only explorer per domain, all spawned in
51	parallel. Agent count = number of genuinely independent domains, within the
52	fan-out cap (see the agent-fanout skill).
53	- For a planned file decomposition: one explorer maps the target file's
54	internal structure (symbol inventory with line ranges, module-level mutable
55	state), a second maps external dependents (importers, test doubles, dynamic
56	imports), and a third reads the merged precedent of a prior similar change,
57	to mirror it.
58	- Every explorer prompt: numbered falsifiable questions naming the suspected
59	files/symbols, an explicit READ-ONLY instruction, and the output contract
60	"file:line references for load-bearing facts; conclusion-oriented; no file
61	dumps". Template in `references/exploration-prompts.md`.
62	- Re-verify the keystone fact yourself. Before any explorer conclusion
63	becomes a headline claim or a plan premise, spot-check the single most
64	load-bearing fact directly (one grep or file read). Explorer reports are
65	hypotheses with citations, not ground truth.
66
67	## Field / literature onboarding (research areas)
68
69	1. Run broad searches yourself first and save the raw corpus (queries and
70	results) to files; then delegate one summarizer per topic family with a
71	hard reading list, exact deliverable path, and a bounded return summary.
72	2. Prefer primary sources (specs, papers, official policy pages); use general
73	web search only as a fallback when a primary source is unreachable.
74	3. Record per-family findings in `research/<family>.md`, synthesize into one
75	survey doc, and record the resulting decision as an Architecture Decision
76	Record (ADR) with a dated log line in `.context/research.md`
77	("Problem, To investigate, Decision (date), Rationale").
78	4. If the project's own docs name a prefe

People who liked this also viewed

6 picks

Type