/project-orientation-sweep

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.

2. Capture a cheap inventory:

   • Prefer scripts/project_inventory.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 node_modules, target, dist, build, .next, .turbo, .venv, and vendor.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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.