# Project Orientation Sweep

> Explore an unfamiliar or recently changed local project before implementation, from tiny repos to large monorepos. Use when Codex needs to map architecture, identify active surfaces, find relevant files for a bug or feature, assess repo health, performance, or errors, choose validation commands, or ground future work in the current checkout before editing.

- Skill: `lassejlv/project-orientation-sweep` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add lassejlv/project-orientation-sweep`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lassejlv/project-orientation-sweep/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lassejlv (https://skillmd.com/u/lassejlv)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lassejlv/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.