Orient Codebase

Orient Codebase

Build an evidence-grounded map that helps the learner reason about the system. Do not produce an exhaustive file inventory.

Workflow

1. Establish the learner context from the conversation. Identify known languages, frameworks, and architectural patterns. Ask only when missing context would materially change the explanation.
2. Read repository instructions and source-of-truth documents first. Then inspect manifests, build scripts, CI, entry points, and the top-level tree.
3. Identify the product shape, deployed processes, runtime boundaries, persistence, external systems, and primary user workflows.
4. Trace at least one representative vertical path from entry point to observable result. Use this path to make abstract boundaries concrete.
5. Distinguish architectural intent documented by the repository from structure inferred from code.
6. Identify only the highest-leverage reading targets and material uncertainties.
7. Stop once the learner has a useful map. Offer deeper exploration by workflow or module instead of front-loading every detail.

Output

Default to this compact shape:

1. System in one paragraph: what it does and how it runs.
2. System map: major boundaries and where state lives, using a short list or text diagram.
3. Start here: three to five files or workflows that build the mental model fastest.

Include a representative workflow when it makes the map easier to understand. Leave build commands, exhaustive module lists, documentation drift, and deeper risks for follow-up unless they are essential.

Explanation Rules

• Ground important claims in source files, configuration, tests, or recorded command output.
• Use file and line references when the client supports them.
• Start with purpose and observable behavior, then reveal implementation detail.
• Adapt explanations to knowledge already stated by the learner.
• Use plain words and short sentences. Give the answer before supporting detail.
• State uncertainty only when it changes the mental model.

Guardrails

• Do not modify files, install dependencies, or run destructive commands.
• Do not infer architecture from directory names alone.
• Do not treat documentation, naming, or tests as proof when runtime wiring contradicts them.
• Do not explain framework basics unless they are necessary for this repository.
• Prefer one concrete execution path over broad abstraction lists.
• Keep the initial orientation concise enough to retain. Expand interactively.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fikrilal
• Source: fikrilal/engineering-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.