First Run Doctor

Onboarding guides rot the moment they are written. New teammates waste hours debugging "works on my machine" issues because documentation reflects a developer's environment from six months ago rather than the current repo state.

What it does

• Detects toolchains by scanning package.json, .nvmrc, pyproject.toml, go.mod, and other version manifests to identify required runtimes.
• Validates environments through a read-only probe of the local PATH, comparing observed binary versions against declared minimums and pins.
• Audits environment variables by cross-referencing keys in .env.example against actual source code usage to find undocumented requirements.
• Map setup commands by identifying installation scripts, database migrations, and build targets within Makefiles or package.json.
• Generates verified guides that label every single instruction as either verified (it ran and passed) or unverified with a specific reason.

How it works

1. Run detection to identify the project's languages, managers, and container configurations based on existing repository files.
2. Execute checks to produce a PASS/FAIL table of binaries, versions, and environment keys present on the current machine.
3. Generate the guide to output a dated snapshot containing prerequisites, setup orders, and troubleshooting steps for failures.

Frameworks & tools

The tool is built with a standard-library-only Python script (onboard.py). It supports detection for Node.js, Python, Go, Rust, Docker, and Makefile-based projects.

Why this beats prompting it yourself

Generic prompts often hallucinate setup steps or blindly trust outdated README files. This skill enforces a strict read-only execution policy and marks its own limitations, ensuring a new hire never follows a "guess" disguised as a command.

Use cases

• Fixing stale READMEs by generating a fresh onboarding guide that reflects the actual code requirements.
• Debugging new hire failures by running a check on their machine to identify missing binaries or env keys.
• Pre-flight checks before demos or interviews to ensure a fresh clone boots correctly without tribal knowledge.
• Environment audits to find discrepancies between version manager pins and engine minimums.

Known limitations

The tool is strictly read-only and will not install packages, run migrations, or start services. It probes for environment key existence only and never reads or prints actual values.