Project Orientation Sweep

Use this skill to build a repo-grounded map before changing code. Scale the sweep to the user's request and the repository size: quick and direct for small projects, lane-based and evidence-driven for large projects.

First Moves

1. Establish boundaries:

- Run pwd, git rev-parse --show-toplevel, git status --short --branch, and git remote -v when inside a git repo. - If the current directory is not a repo, identify nearby independent repos instead of assuming a monorepo. - Preserve unrelated dirty work.

1. Capture a cheap inventory:

- Prefer scripts/projectinventory.sh [path] when available, then follow up with targeted reads. - Otherwise use rg --files, git ls-files, top-level manifests, and shallow directory counts. - Exclude generated or vendor-heavy directories such as nodemodules, target, dist, build, .next, .turbo, .venv, and vendor.

1. Classify scale:

- Small: one app/library, one main stack, a few obvious entrypoints. - Medium: several packages/services or mixed stacks, but one likely task surface. - Large: monorepo, many apps/packages, many manifests, generated code, or unclear ownership. - For medium or large projects, read references/scale-playbooks.md before deeper exploration.

1. Identify the stack:

- Read manifests first: Cargo.toml, Package.swift, Package.resolved, bun.lock, package.json, go.mod, pyproject.toml, requirements*.txt, Dockerfile, justfile, Makefile, railway.json, wrangler.toml. - Prefer rg --files and targeted rg searches over broad filesystem walking. - For JS/TS projects, prefer Bun commands when the repo supports them. Respect the existing package manager when only npm, pnpm, or yarn lockfiles/scripts are present.

1. Map active surfaces:

- Find entrypoints, route files, app shells, services, migrations, config loaders, scripts, and tests. - For user-visible bugs, search exact UI/log/error text first. - For performance work, identify the hot loop or refresh path before editing. - For native apps, separate host UI ownership from core/runtime libraries. - For broad requests, map ownership boundaries before reading implementation details.

1. Decide the output shape:

- If the user asked only to understand the project, return a compact architecture map, main workflows, validation commands, and risks. - If the user asked to fix obvious issues, make only high-confidence, low-blast-radius fixes after the map is clear. - If the surface is broad, split research lanes or use subagents only when their scopes are disjoint or research-only.

1. Validate:

- Run the narrowest meaningful checks for touched areas. - Rust: cargo fmt --check, cargo check, targeted cargo test, or repo just tasks. - SwiftPM/macOS: swift build, existing build/run scripts, and smoke checks where available. - Bun/TS: bun run scripts, typecheck/lint/build, and live HTTP smoke tests for web apps. - Go: go test ./... unless the repo has a narrower test target. - Shell/Python utility repos: bash -n, python3 -m compileall, and endpoint/file smoke tests. - Large repos: prefer the nearest package/app validation first. Run whole-repo checks only when they are known to be reasonable or the user asked for a broad pass.

Exploration Depth

Use the lightest pass that can answer the user:

• Orientation only: map boundaries, stack, entrypoints, data flow, commands, risks.
• Feature prep: map the relevant surface, adjacent tests, extension points, and likely implementation files.
• Bug/performance investigation: start from symptoms, logs, UI text, traces, or failing checks, then trace source to sink.
• Broad audit: inventory first, split into lanes, sample representative modules, and label confidence.
• Fix request: orient enough to avoid accidental damage, then implement the narrowest credible change.

Output

Lead with the concrete result:

• Map: repo boundary, scale classification, stack, important entrypoints, and current branch/dirty state.
• Active surfaces: files/directories that matter for the request and why.
• Findings: only evidenced issues or risks, ordered by impact and labeled when inferred.
• Changes: files touched, if any.
• Verified: commands and smoke tests run.
• Next: one or two genuinely useful follow-ups.

Guardrails

• Do not invent architecture from filenames alone; label inferences when direct file evidence is missing.
• Do not read the whole repo when a manifest, route, test, or error string can identify the relevant surface.
• Do not turn an orientation request into a large refactor.
• Do not run expensive full-repo commands before identifying the stack and likely blast radius.
• Do not push unless the user asks.
• Do not delete or rename files unless the user explicitly requested that operation or the issue is unambiguously stale and validated.