Codebase Orientation

Getting started in a massive, unfamiliar codebase usually involves hours of aimless wandering and broken builds. This skill replaces guesswork with a systematic orientation process that maps build commands, entry points, and state locations before you write a single line of code.

What it does

• Automatic reconnaissance runs scripts to identify source size, language distribution, and manifest-advertised commands.
• Dependency analysis extracts ground truth from package.json, go.mod, or Cargo.toml instead of relying on potentially stale READMEs.
• Behavioral search locates logic using error strings, log messages, and route paths rather than unstable function names.
• Map generation produces a concrete ORIENTATION.md file containing verified build/test commands and module layouts.
• Path tracing identifies the specific flow from entry point to data store for the feature you need to modify.

How it works

1. Analyze manifests by reading the project's build files and CI workflows to find the honest build process.
2. Execute reconnaissance using repo-map.sh to get a high-level view of directory sizes and entry points.
3. Answer five core questions regarding build commands, entry points, directory layout, state locations, and feature flow.
4. Verify the map by running the identified build and test commands to ensure they actually work.
5. Commit the map to docs/ORIENTATION.md as a permanent reference for the next developer.

Frameworks & tools

This tool works with any language using standard manifests like npm, pip, cargo, go, or maven. It uses grep for behavioral searching and basic shell scripts for repository analysis.

Why this beats prompting it yourself

Standard LLMs often hallucinate project structures or suggest outdated commands from the README. This skill enforces a "run-over-read" philosophy, verifying every command and directory path against the actual filesystem before reporting it.

Use cases

• Onboarding to a legacy project where the original developers are no longer available.
• Pre-edit mapping to ensure the first change in a new repo doesn't break the build.
• Hand-off preparation to provide the next developer with a verified map instead of a mystery.
• Bug hunting by using behavioral search recipes to find exactly where an error string is triggered.

Known limitations

Does not support reading or mapping secret material like .env values or credential stores. Designed for repository structure, not deep business logic audits.