SAYLOR Convert an unfamiliar repository into a reproducible setup, launch, test, and deployment plan without guessing at dependencies.
The result you're building
A clean-room runbook that takes a freshly copied repository to a healthy local service using pinned dependencies, explicit configuration, a repeatable start command, a functional test, and a documented deployment boundary.
Use when: a repo has incomplete or contradictory setup instructions; you must evaluate client software without trusting install scripts blindly; it works on one machine but not another.
Not a substitute for: running an unknown repo on production hosts or with valuable credentials; assuming a successful build proves the service is safe or deployable.
Before you change anything, collect: repo URL/source plus exact commit hash; README, lockfiles, manifests, container files, migrations, example env files; a disposable account/container/VM/sandbox with no production secrets; expected behavior/health route/ports/external deps; license/permission to use required third-party services.
Understand the system first
- The repository is evidence, not documentation — manifests, lockfiles, imports, CI config, and entry points reveal the actual runtime more reliably than prose.
- Build, start, healthy, and correct are separate gates — compilation proves syntax; a running process proves it didn't exit; a health endpoint proves a narrow check; functional tests prove the requested behavior.
- Configuration is part of the product — env vars, migrations, ports, storage, callbacks must be versioned as a schema even with secrets excluded.
Evidence-to-decision map
| Evidence | Likely layer | First check | Meaning |
|---|---|---|---|
| No obvious start command | Entrypoint | Manifests, Dockerfile, CI, imports | Use the command CI/deployment actually uses |
| Install fails deterministically | Runtime/deps | Compare runtime version vs lockfile manager | Use matching runtime + frozen install, don't regenerate lockfile first |
| Starts then exits | Config/dependency | Capture exit code + first app error | Missing env, unreachable DB, migration, bind, or permission |
| Process up but feature fails | Functional layer | Call health + one core operation directly | Trace request, DB, queue, external API separately |
Step-by-step procedure
01 Fingerprint without executing.
git rev-parse HEAD
find . -maxdepth 2 -type f | sort | sed -n '1,200p'
rg -n 'postinstall|curl |wget |migrate|seed|PRIVATE_KEY|TOKEN' .Multiple lockfiles are a reproducibility warning.
02 Write the environment contract. For every variable: type, required/optional, safe example, consumer, failure behavior. Separate secrets from ordinary config.
rg -n 'process\.env|os\.environ|getenv|env::var|VITE_|NEXT_PUBLIC_' .Destination/auth/billing/network-affecting variables need explicit validation and a safe default of refusal.
03 Install exactly from the lockfile.
python3 --version; node --version 2>/dev/null; cargo --version 2>/dev/null
npm ci # or: pnpm install --frozen-lockfile
python3 -m pip install --require-hashes -r requirements.txtA frozen-install failure means the repo isn't reproducible as committed — preserve that result before updating anything.
04 Run preparation stages separately. Lint/typecheck, build, migration status, migration, start — as distinct recorded steps. Back up any non-disposable database first.
npm run lint --if-present
npm run build --if-present
npm run start --if-present05 Prove health and one real outcome.
ss -ltnp
curl -fsS http://127.0.0.1:PORT/health
curl -i http://127.0.0.1:PORT/CORE_ROUTEConfirm the response, persistence side effect, and log correlation ID agree.
06 Convert discovery into a handoff runbook. Prerequisites, setup, config schema, start/stop, health, backup, migration, test, and recovery from a clean checkout — a second run should need no undocumented clicks.
Worked example
A Node API installs but exits with ECONNREFUSED 127.0.0.1:5432. npm ci succeeds; DATABASE_URL is read but .env.example lists it with no local DB setup; no process listens on 5432. Decision: the build is valid — the missing piece is PostgreSQL provisioning. Fix: started an isolated Postgres container, set a test-only DATABASE_URL, ran migration status then migrations, started the API and exercised health plus one DB-backed route. Proof: a clean checkout completes install, migrations, start, health, and the DB-backed test using only the documented runbook.
Verify, recover, hand off
Complete when: a clean checkout at the recorded commit installs without modifying the lockfile; required config fails fast with a useful message when absent; build/migrations/start have distinct commands and logs; health and one core test pass against disposable deps; no production secrets entered the evaluation environment.
Rollback: destroy disposable dependencies rather than manually cleaning them; restore a database backup if an authorized migration changed non-disposable data; return to the original lockfile/runtime if an update attempt fails.
| Symptom | Usually means | Next move |
|---|---|---|
| Install modifies the lockfile | Wrong package manager/version or non-frozen command | Restore committed lockfile, use matching locked install |
| Health passes but core route fails | Health check too shallow, or wrong instance/port | Test dependencies individually, improve readiness semantics |
| Works only as root | Hidden permission/privileged-port assumptions | Run as intended user, fix the narrow resource boundary |
| Clean checkout can't repeat setup | Untracked file, global package, or manual step required | Diff environment, convert into documented config |
Handoff record: repo origin + exact commit; runtime, package manager, frozen-install command; config schema with safe examples and secret boundaries; build/migration/start/stop/health/core-test commands; known limitations, deployment assumptions, rollback steps.
For agents
Inputs: repo (reference + immutable commit), target (OS/arch/runtime/deployment shape/allowed ports), secretsAvailable (names only, never values), successTest (health + functional acceptance criteria). Output: diagnosis, plan (ordered, risk-tagged), verification (pass/fail checks), handoff (sanitized record, risks, rollback state). Same refusal/escalation/confidence rules as the standard series: refuse secret-requiring input, stop at authority/budget/reversibility limits, escalate on missing evidence, score confidence from observation quality not familiarity.
References
- https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
- https://docs.npmjs.com/cli/v11/commands/npm-ci
- https://packaging.python.org/en/latest/tutorials/installing-packages/