Raw view: Codebase Onboarding, Day One
No invisible, zero-width, or bidi-control characters detected.
# Codebase Onboarding, Day One
Produce an accurate map of the repository at `{{REPO_PATH}}` and get it running locally, in roughly {{TIME_BUDGET_MINUTES}} minutes. Focus area, if any: {{FOCUS_AREA}}. This is a read-and-run workflow: do not modify tracked files. Everything you write goes into a single notes file outside the repo or in an untracked scratch location.
Every statement in the notes must cite the file it came from. "Probably" is allowed only when labeled.
## Phase 1: Surface scan (10% of budget)
1. List the top two directory levels. Read, in this order if present: README, CONTRIBUTING, the manifest(s) (package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml), the CI config, Dockerfile or compose file, and any `docs/` index.
2. Record: languages and versions, package manager, declared scripts or build targets, test framework, CI steps, and how the project is deployed if the files say.
3. Note every claim in the README that you will later verify (install steps, commands, ports).
**Artifact:** `ONBOARDING.md` section "Facts from the surface", each fact with its file.
## Phase 2: Build and run (30% of budget)
4. Follow the README's setup steps exactly as written. Record each command and its result. Where a step fails, record the error, find the fix (often a missing env var or tool version), and record the fix separately from the README's instruction. Do not edit the README; the discrepancy list is a deliverable.
5. Run the test suite. Record: command, duration, pass/fail counts, and any tests that are skipped or flaky on first run.
6. Start the application (or the primary entry point) and exercise one end-to-end path: an HTTP request, a CLI invocation, a rendered page. Record exactly what you did and what came back.
7. **Check:** you have a green test run and one successful end-to-end interaction. If not within 40% of the budget, STOP, record where you are blocked and what you tried, and ask for help; do not spend the remaining time fighting the environment.
**Artifact:** "Build log" section with commands, results, and "README discrepancies" list.
## Phase 3: Architecture map (40% of budget)
8. Find the entry points: main functions, route registrations, CLI command tables, scheduled jobs, message consumers. List each with its file.
9. From each entry point, trace one request or invocation through the layers until it hits storage or an external call. Record the sequence of modules as a short path (`routes/orders.ts -> services/order.ts -> repo/order.ts -> db`). Do this for 2-4 paths, prioritizing {{FOCUS_AREA}}.
10. Identify the core data model: the main entities, where they are defined (schema, ORM models, types), and how they relate. Keep to the 5-10 that matter.
11. Identify external dependencies the code calls at runtime: databases, queues, third-party APIs, feature-flag services. For each, note where it is configured and how it is mocked in tests.
12. Note the conventions you observe: directory layout rules, naming, error handling pattern, logging, how configuration is read, how tests are organized. Cite two examples of each.
13. Record what surprised you: unusual patterns, dead-looking code, TODOs with dates, large files, places where the README and the code disagree.
**Artifact:** "Architecture" section with entry points, traced paths, data model, external dependencies, conventions, and surprises.
## Phase 4: Questions and next steps (20% of budget)
14. Write the questions you could not answer from the code, grouped by whom to ask (team lead, original author per `git log`, ops). Each question names the file or behavior that prompted it. Aim for 5-10; fewer than 3 suggests the scan was shallow.
15. Propose a first task for yourself: a small, low-risk change in {{FOCUS_AREA}} that would exercise the build, test, and review loop (a test for an untested path, a doc fix from the discrepancy list). Do not do it in this workflow.
16. **STOP POINT.** Present `ONBOARDING.md`. The reader should be able to verify any line by opening the cited file.
**Final artifact:** `ONBOARDING.md` with sections: Facts from the surface, Build log, README discrepancies, Architecture, Questions, Proposed first task.
## Rules throughout
- Read files fully before describing them; do not describe a module from its name.
- Cite a file for every factual statement; label inferences.
- Do not modify tracked files, install global tools without noting it, or run commands whose effect you do not understand (migrations against a non-local database, deploy scripts).
- Use `git log` and `git blame` to find owners and recent change areas; do not read the whole history.