study-repo

Study Repo

Answer questions by reading the codebase, not by guessing from filenames.

Process

1. Classify the Question

Identify which kind of answer the user needs:

• System overview — what the repo does and how it is organized.
• Feature trace — how a specific behavior is implemented.
• Usage check — whether the user can use an API, command, package, component, or pattern in a certain way.
• External package behavior — how a dependency's documented contract, implementation, versions, or known limitations actually work.
• Change readiness — what must be understood before planning a change.

Use the classification to choose the evidence needed; do not announce it unless it helps explain the scope.

2. Find the Anchors

Read the smallest set of primary sources that can answer the question. The following are options, not a required reading sequence; stop once evidence answers the question and reuse current context:

1. Repo-level docs and package/config files for orientation.
2. Entry points, routes, commands, public exports, or tests related to the question.
3. Definitions and call sites for the relevant functions, types, components, or modules.
4. Existing tests or examples that show intended behavior.
5. For external packages, official documentation, release notes, source code, tests, examples, and type definitions for the installed or requested version.

Prefer semantic navigation and fast search. Treat docs as helpful, but verify behavior against code when possible.

When suitable tools are available, use them for package verification:

• Use an official documentation source to check documented APIs, configuration, and versioned behavior; for example, Context7 when available.
• Use source search or package source to inspect implementation, tests, examples, and type definitions; for example, Octocode or GitHub source search when available.
• Prefer the installed package version when the local project pins one; otherwise state which version or branch was inspected.
• If docs and source disagree, report the conflict instead of smoothing it over.

3. Trace the Path

For feature questions, follow the behavior from the public entry point inward until the important state changes, IO, or domain decisions are visible.

For usage questions, verify:

• The public interface the user would call.
• Required inputs, configuration, ordering, or environment.
• Error modes and unsupported cases.
• Existing tests, examples, or docs that confirm the usage.

4. Separate Certainty Levels

Keep the answer honest:

• Facts — directly supported by code, tests, docs, or command output.
• Inferences — likely conclusions from structure or naming.
• Unknowns — things not proven from available sources.

Do not present an inference as a fact.

Output

Return a concise answer with:

• Short answer — the direct answer first.
• How it works — the important path through the repo.
• Code references — files and symbols that support the answer.
• Caveats — unsupported cases, unknowns, or assumptions.
• Next step — if this should become a code change, recommend /plan-it.

Completion Criterion

The study is complete when the user can tell:

• Where the relevant behavior lives.
• How the main flow, API contract, or package behavior works.
• What evidence supports the answer.
• What remains uncertain, if anything.