generalist-playbook

Generalist Playbook (any stack, end to end)

This is the procedure for working expertly in a codebase you have never seen. The core discipline: the repo outranks your training data. Every default you carry — favorite test runner, error style, directory layout — is a guess until the repo confirms it. The loop below replaces guessing with reading, in a fixed order, before the first line is written.

Operating loop

1. Detect the stack from manifests, in this order (first hit usually wins; multiple hits = polyglot repo, note each root): go.mod → Go; package.json → Node/TS/JS; Gemfile → Ruby; pyproject.toml / requirements.txt → Python; Cargo.toml → Rust; pom.xml / build.gradle* → JVM; composer.json → PHP; *.csproj → .NET. File extensions alone are NOT detection — a repo full of .ts may be Deno, Bun, or a browser extension with no Node at all.
2. Read the lockfile for exact versions (go.sum, package-lock.json / yarn.lock / pnpm-lock.yaml, Gemfile.lock, poetry.lock / uv.lock, Cargo.lock). The lockfile decides two things: the package manager you must use, and the major versions your advice must match. Advice written for a different major version of a pinned library is a bug you ship.
3. Discover the project's OWN commands — never invent them. Look, in order: package.json "scripts", Makefile / justfile / Taskfile, CI config (.github/workflows/*.yml, .gitlab-ci.yml, .circleci/). Whatever CI runs is the ground truth for build/test/lint. Write down the exact test, lint, typecheck, and build invocations before coding.
4. Read 2–3 source files neighboring your change area. Extract, don't assume: naming convention, import/module style, error-handling shape (exceptions vs error returns vs Result), logging pattern, validation pattern. Your code must be indistinguishable from a regular contributor's.
5. Read one existing test file for the same layer you'll touch. Note the runner, assertion style, fixture/mocking approach, and file-naming pattern (*_test.go, *.spec.ts, test_*.py, …). You will write tests in exactly this dialect.
6. Grep before you write. Before creating any helper, type, constant, or endpoint: grep -ri for its probable names AND its behavior (the format string, the URL path, the field name). Most "missing" utilities already exist under a name you didn't guess.
7. Vertical-slice the feature. Build the smallest END-TO-END path first — one input, through every layer, to one observable output — and make it pass the project's own checks. Only then widen (more fields, more cases, more endpoints). A working thin slice beats three finished layers that have never met.
8. Implement the failure path in the same slice as the happy path. Bad input, missing record, downstream error — handled in the repo's established error style, with at least one test each way. "Happy path now, errors later" is how half-features ship.
9. Run the discovered commands; quote real output. Fix failures before handing off. If a check fails on the BASE commit too, prove it (git stash → run → git stash pop) and report it as pre-existing rather than fixing unrelated breakage.
10. Report with claims labeled VERIFIED (ran it) / REASONED (read it) / ASSUMED (unchecked), plus anything deferred or discovered out of scope.