Shaelz/codebase-orient-skill

Skill: codebase-orient

Purpose

Orient Claude to the current state of this repo before non-trivial work. It creates or reconciles a fixed, provenance-backed four-artifact package in docs/ai/. Source code and project configuration remain authoritative.

When to use this skill

Use this skill when

• Entering a new or unfamiliar repo
• Starting a fresh session after meaningful time away from the repo
• Before broad or multi-file implementation work
• Before refactors, cleanups, architecture planning, or agent handoff
• After structural changes: routes, schema, auth, deployment, config, or admin surfaces
• When docs/ai/ is missing, stale, incomplete, or internally inconsistent
• When repo structure, change surfaces, deploy targets, auth behavior, admin routes, commands, or test shape are unclear
• When the agent would otherwise spend significant context rediscovering what is already in or near docs/ai/
• Any time the user says "scan", "orient", "understand", "map", "review", "audit", "survey", "familiarize", or "before I start"

Skip this skill when

• Making a tiny, local, known edit to a single file
• Fixing a one-file bug where the relevant file and the change are already clear
• Making copy-only or string-only changes
• The task is scoped tightly to files already verified in the current context
• docs/ai/ was just refreshed and the task is narrow enough not to need a full orientation pass

Token-aware use guidance

docs/ai/ is an orientation cache. A fresh cache reduces repeated repo-discovery token cost across sessions and agent handoffs.

• If docs/ai/ is fresh and complete: read it as context and proceed. Skip re-running orientation.
• If docs/ai/ may be stale or is missing: run the skill to refresh the cache. The upfront token cost amortizes across the work ahead.
• If the task is tiny and the target file is already known: skip orientation. Use targeted reads instead.
• If the agent would spend many tokens rediscovering what docs/ai/ already captures: refresh it.

Do not save tokens by skipping orientation and then guessing at structure. If broad repo discovery would otherwise be repeated or expensive, refresh the cache instead.

Hard rules during orientation

• Do not modify application or source code.
• Do not refactor.
• Do not commit.
• Verify claims against source code before writing them.
• Mark every meaningful claim with a confidence label.

Normal mode vs dry-run mode

Normal mode (default - use when the user does not specify):

• Resolve small task-relevant uncertainties automatically by reading source files
• Create a full package on first use in a clean repository
• Reuse an exact-current clean package without rewriting it
• Treat an unspecific request to refresh or reconcile as a full reconciliation
• Report what changed at the end

Dry-run / report-only mode (use when the user says "dry-run", "report only", "don't write", "propose changes first", "audit only", "no writes", or similar):

• Inspect and collect proposed changes
• Report proposed edits to docs/ai/ without writing them
• Wait for explicit approval before writing

If mode is not specified, default to Normal mode.

Lifecycle and write safety

• Explicit refresh: Refresh or reconcile only when the user explicitly asks after an exact-current package is found.
• Scoped refresh: Follow an explicit user scope and its direct dependencies. Record scoped coverage without advancing or claiming a package-wide full snapshot. Do not create a partial supported package before a full package exists.
• Legacy adoption: Markdown artifacts without ORIENTATION_STATE.json are legacy material. Inspect them, but obtain explicit approval before writing a manifest or changing them. Reconcile from source after approval.
• Dirty tree: Before writing state that represents uncommitted work, ask whether to write a dirty snapshot or report only. Record the tree condition; keep it marked dirty until a clean refresh replaces it.
• No usable Git history: Perform a full reconciliation and record that revision comparison is unavailable.
• Manual edits: Orient owns the package. Do not promise merge or preservation behavior for manually edited Orient state.

Confidence labels

• Fact: directly verified in code or docs
• Strong inference: supported by multiple files
• Weak inference: plausible but not confirmed
• Unknown: needs more inspection before editing

Distinguish how a claim was established:

• independently verified from source/config: claim checked against the actual source or config file, not taken from docs
• inherited from existing docs: claim taken from CLAUDE.md, README, or other documentation without independent verification
• inherited then verified: claim originated in docs and was subsequently confirmed against source
• path existence confirmed: file found but not read
• partial read: portion of the file inspected; may not capture full context
• full source read: complete file content inspected
• inferred from implementation: deduced from how code behaves, not explicitly stated
• inferred from comments/tests/fixtures: sourced from non-authoritative context; treat as Strong inference at best
• behavior verified by test: confirmed by passing test execution
• unknown: basis not established; do not present as Fact

In final reports and orientation docs, label each non-trivial claim with one of the above origins so readers can judge which claims need re-verification before acting on them.

Discovery order

Customization note: The discovery order below is intentionally broad and works across most project shapes without editing. You can tune the file paths and order for a specific project, but this is optional - not required before first use.

Execute in this order:

1. Project instruction files such as CLAUDE.md, AGENTS.md, and README.md, if present - product purpose, agent rules, project conventions. Docs-as-hypotheses rule
   • Treat these documents as helpful hypotheses, not authoritative truth.
   • Extract high-impact factual claims about architecture, routes, deployment, tests, and source-of-truth files.
   • Verify those claims against source code before relying on them. Focus on claims that would affect future edits; do not audit every sentence.
   • Do not copy claims from these docs into CODEBASE_MAP.md without labeling whether they are independently verified from source/config or inherited from existing docs.
   • If an instruction doc is stale or misleading compared to what the source shows, record the drift in OPEN_QUESTIONS.md under the hidden-risk reporting rule and label it as documentation drift.
   • Map the instruction-layer topology: note which instruction files are present (e.g., CLAUDE.md, AGENTS.md, .claude/settings.json) and at which scope (project-local vs user-level). Record this in CODEBASE_MAP.md; it helps future agents know which rules apply.
2. Project manifest (e.g., package.json, pyproject.toml, Cargo.toml) - deps, scripts, build/test commands
3. Build and config files (e.g., framework config, bundler config) - adapter, build config
4. scripts/ directory, if present - may contain manually-run tooling not represented in package scripts or CI
5. Entry points and routing layer - all pages, controllers, or API routes
6. Core business logic - domain types, models, scoring, report logic
7. Server-side services - auth, db/schema, email, external integrations
8. UI/presentation layer - components, views, templates
9. Internationalisation or copy files - locale files
10. Request lifecycle / middleware - hooks, interceptors, middleware
11. Database layer - migrations, schema snapshots
12. Tests - test structure and coverage shape
13. Documentation - existing docs, verification matrices. If a release plan, milestone tracking doc, or version changelog is found, add a ## Release status section to CODEBASE_MAP.md summarizing the current version, active milestone, and what is blocking the next release. Omit this section if no release lifecycle artifact is present.
14. Known uncertainty

Framework-specific probes

Apply these probes in addition to the generic discovery order when the relevant framework is detected.

The reusable skill currently includes one explicit tuned probe set for SvelteKit. Other frameworks currently use the generic discovery order unless later live-fire or eval evidence justifies a dedicated tuned probe section.

SvelteKit

Glob the following file patterns when a SvelteKit project is detected:

• src/routes/**/+page.svelte: UI route pages; each file is a route candidate; check subdirectories, not only the top-level src/routes/+page.svelte
• src/routes/**/+page.server.ts: server-side data loading, form actions, and route-level access control
• src/routes/**/+layout.svelte: shared layout shells
• src/routes/**/+layout.server.ts: server-side load functions for layout-level auth, session, or data
• src/routes/**/+server.ts: API endpoints and server-only request handlers

Server-side route files (+page.server.ts, +layout.server.ts, +server.ts) are critical for understanding auth, data loading, form actions, API endpoints, and route-level access control. Do not skip them when mapping routes or change surfaces.

• The standard app shell template is src/app.html.
• Adapter choice in svelte.config.js determines deployment target - confirm before making deployment-related claims.

CI/deployment precision rule

When reading CI or deployment workflow files, preserve operationally relevant detail. Do not round down specifics into vague summaries.

Capture and report:

• concurrency group name (which runs compete with each other)
• cancel-in-progress behavior - if true, say "newer runs cancel in-progress runs of the same group", not merely "prevents parallel deploys"
• fail-fast behavior
• deploy artifact paths
• release naming format including any timestamp or hash components
• retention and pruning policy for old releases or artifacts
• manual vs automatic trigger conditions
• required secrets and environment variables
• whether deployment overwrites in place, stages to a temp path, uses symlinks, or uses versioned release directories

Label CI/deployment claims with independently verified from source/config when read directly from the workflow file. Do not summarize these details in ways that lose precision that an operator would need during an incident.

Read-depth heuristic

Do not read every large CSS, config, or generated file by default.

• Full read: files that directly affect the requested task (entry points, routing, auth, schema, build config, the file to be edited).
• Partial read or path-confirmation only: secondary surfaces such as large style sheets, vendored code, generated output, or config files not relevant to the task. If you only confirm a file's path or read a portion, say so explicitly in the report using the path existence confirmed or partial-read labels defined under Confidence labels.
• Skip: files that are clearly out of scope (e.g., binary assets, lock files, test snapshots) unless a specific question makes them relevant.

When in doubt, prefer confirming existence first and reading fully only if a claim requires it.

Path existence vs content read

Path existence alone is sufficient for low-risk inventory claims - confirming a directory structure, listing file counts, or noting that a config file is present.

Read the actual file content when the claim affects behavior, architecture, risk, commands, deployment, auth, routing, or change surfaces. Do not label a claim as independently verified from source/config based on path existence alone when the file is cheap to inspect and its content would materially affect the map.

Small source-of-truth file read rule

If a small file appears to define vocabulary or source-of-truth tokens used throughout the project, read enough of it to verify the vocabulary rather than inheriting the vocabulary from docs.

Examples where this applies:

• CSS custom-property token files
• route or menu config files
• small schema or constants files
• command or plugin registries

Use a partial read when that is sufficient. Label the resulting claims with the appropriate claim origin (partial read, full source read). Do not label them as independently verified from source/config if you did not actually read the file.

Cheap artifact glob rule

Before leaving an open question about the existence or scope of static assets, scripts, generated outputs, documentation, tests, migrations, or config files, resolve it with a cheap path glob.

Common glob patterns to try:

• static/**/*
• public/**/*
• scripts/**/*
• tests/**/* or test/**/* or spec/**/*
• .github/workflows/*
• docs/**/*
• migrations/**/*
• dist/**/* or build/**/*

Do not deeply read all matched files by default. Use the glob to resolve existence and scope questions cheaply. Follow up with targeted reads only when a specific file's content is needed.

Open question quality rule

Do not leave an open question in OPEN_QUESTIONS.md if it can be resolved with one cheap path glob or one small-file read.

Leave a question open only when resolving it would require:

• broad exploration that is disproportionate to the task
• external documentation that is unavailable
• commands that could have side effects
• deep reads of files that are irrelevant to the current task

If a glob or small read can close the question, close it and label the basis.

Supported orientation package

A full supported package always contains:

• docs/ai/ORIENTATION_STATE.json
• docs/ai/CODEBASE_MAP.md
• docs/ai/CHANGE_SURFACES.md
• docs/ai/OPEN_QUESTIONS.md

ORIENTATION_STATE.json is the single freshness and provenance record. It records the format, producer and Orient version, package-wide source revision and ref where available, tree condition, expected artifact inventory, reconciliation mode, and compact scoped coverage where applicable. Keep it a compact current-state record, not telemetry or an append-only diary.

The Markdown artifacts do not carry Last refreshed: lines. OPEN_QUESTIONS.md always exists; when no material questions remain, state that explicitly.

In target repos, these files should be committed to version control. They are authored narrative that improves across sessions, not regenerable cache - do not add them to .gitignore in target repos.

Before staging, format all created/updated files if the project has a discoverable formatter that covers Markdown (e.g., Prettier, markdownlint). If a formatter is missing, unavailable, not configured for Markdown, or its invocation would fail, skip formatting, note this clearly in the orientation report, and continue. Do not treat missing formatter support as an orientation failure.

CHANGE_SURFACES mapping guidance

When populating docs/ai/CHANGE_SURFACES.md, include entries for these change types in addition to the standard surfaces (routes, styling, schema, tests, config):

• Auth/admin/operator UX changes: admin panels, operator dashboards, internal tooling surfaces; note any accessibility requirements or WCAG targets found in source or docs
• Deployment-sensitive changes: flag files whose changes should prompt a smoke check after deploy; note likely smoke-check entry points (e.g., login page, health endpoint, main route)
• Docs-impact changes: for each major subsystem, note which project docs need updating alongside code changes (e.g., "changes to the auth flow should also update docs/auth.md"). For check or validation scripts found in scripts/, note what file types or patterns they enforce as a constraint on docs-impact changes (e.g., ASCII-only enforcement that applies to all tracked Markdown).

Do not create separate docs/ai/ files for smoke-check lists or handoff notes - record them inline in CHANGE_SURFACES.md.

No-date-only-churn rule

Do not rewrite the package solely to change a date, timestamp, or freshness marker. Freshness belongs in ORIENTATION_STATE.json, and a normal exact-current reuse leaves every artifact unchanged.

Staleness and update rule

The docs/ai files are orientation aids, not ground truth. Always verify against source code before editing.

When re-running orientation on a repo that already has docs/ai/ files, read them to understand what was previously recorded - but treat their structural claims as hypotheses requiring source verification, the same way the docs-as-hypotheses rule applies to CLAUDE.md and README.md. Do not accept prior orientation claims as discovery input for the new analysis pass; verify them against source before carrying them forward.

After any structural change, check whether the package needs reconciliation. Update only relevant content unless a full reconciliation is requested or required by unsafe provenance comparison.

Cross-file consistency rule

The four docs/ai/ artifacts must remain coherent with each other. After any update, verify:

• Resolved questions: if OPEN_QUESTIONS.md marks a question resolved, remove or update any stale "unknown" or "needs investigation" language in CODEBASE_MAP.md and CHANGE_SURFACES.md that referred to the same item.
• New change surfaces: if a change surface is added to CHANGE_SURFACES.md, check whether CODEBASE_MAP.md should mention the associated area or file.
• New map uncertainty: if a claim in CODEBASE_MAP.md becomes uncertain, check whether the corresponding open question exists in OPEN_QUESTIONS.md; add or update it if not.
• Contradictions: do not let one file say "unknown" or "unresolved" while another says "resolved" or "confirmed" - unless the distinction is explicitly explained.

Apply this as a final consistency pass after reconciling any package artifact.

Orientation completion rule

Before finishing orientation, classify every unresolved open question as one of:

• Blocking: must resolve before safe work on the current task (e.g., unknown auth behavior before touching auth, unknown API shape before touching that route)
• Relevant but non-blocking: useful context for the task but work can proceed without it
• Background: not needed for the current task at all

Also classify each open question by who can act on it:

• Agent-closable: resolvable by running a command, reading a file, or making a local change
• Human-required: requires external access, permissions, approvals, or out-of-band action

This second axis lets a new agent immediately identify which items it can work on autonomously without waiting for human input.

Then apply these rules:

1. Automatically resolve Blocking questions by reading the minimum necessary files - unless the user explicitly requested dry-run or report-only mode.
2. Apply docs/ai updates without asking first when only docs/ai files need to change. Do not prompt for approval on small documentation corrections unless the user asked for it.
3. Do not stop to prompt the user for permission to resolve small documentation uncertainties. Use judgment and proceed safely within the hard rules.
4. Stop and hand off only when:
   • relevant change surfaces are identified
   • blocking unknowns are resolved or explicitly marked as non-blocking
   • docs/ai is current enough for the requested task
   • the next action is clear

For Relevant-but-non-blocking and Background questions: record them in OPEN_QUESTIONS.md with their classification and move on. Do not let them block the orientation report.

Orientation report discipline

The final orientation report must distinguish between docs that changed and docs that did not. Label each docs/ai/ file with one of:

• Created: file did not exist; was created this pass
• Substantively updated: content and manifest provenance changed
• Verified current / unchanged: content inspected and confirmed accurate; file not rewritten
• Proposed only: dry-run mode; change proposed but not written
• Skipped: file not inspected this pass; state why

Do not label a file as "updated" or "refreshed" if only its date changed. A file with no substantive changes must be reported as verified current / unchanged.

Agent handoff summary

When orientation is requested before an agent handoff, append a compact Handoff summary block to the orientation report:

• Snapshot: 3-5 key facts: framework, entry point, auth mechanism, deploy target, test approach
• Blocking open questions: anything that must resolve before safe work begins
• Critical change surfaces: top 3-5 surfaces most likely affected by the incoming work
• Recommended first action: what the receiving agent should do first

Keep it under 150 words. Do not create a separate docs/ai/ file for it.

Project-local runtime mutation boundary

Do not create, update, specialize, migrate, or preserve .claude/skills/codebase-orient/SKILL.md during orientation. A repo-local installed skill is runtime material, not Orient state. Existing specialized copies are legacy local state with no automatic migration or overlay contract.

Report useful project-specific paths in the supported docs/ai/ package. Do not invent a replacement overlay system.

Hidden-risk reporting rule

Be concise by default, but go deeper when depth changes the decision.

During orientation, actively look for hidden risks that could affect future work, reproducibility, safety, or correctness.

If any of the following appear, include a Potential drift / hidden risk section in the final report:

• source file vs generated file mismatch
• local copy vs packaged copy mismatch
• repo-local config vs global/user config mismatch
• runtime registry vs filesystem source mismatch
• committed source vs ignored runtime artifact mismatch
• docs claiming one thing while code suggests another
• tests passing but coverage not proving the behavior
• path existence without full source read
• behavior inferred from comments, fixtures, or tests rather than implementation
• setup that works in this session but may fail after restart, reinstall, deploy, rebuild, cache clear, or future Claude session
• release validation records or gate scripts present in the repo (if found, note in CHANGE_SURFACES that any file change after a validated candidate requires a re-check before tagging)

For each item, report:

• Evidence
• Risk
• Confidence
• Recommended action
• Whether action is needed now or can be deferred

If a hidden-risk item affects reproducibility, future installs, runtime behavior, or source-of-truth clarity, classify it as Blocking or Relevant but non-blocking, not Background.

Source-of-truth drift detection rule

When multiple copies or layers exist, explicitly map them before declaring the system current.

Check for:

• editable source files
• generated files
• packaged archives
• runtime/plugin registry copies
• global/user-level copies
• project-local copies
• committed repo files
• ignored local files
• cache/session-loaded copies

For each layer, identify:

• what it is used for
• whether it is authoritative
• whether it is tracked by git
• whether it is regenerated from another source
• whether it can overwrite another copy
• whether it survives restart, reinstall, clone, deploy, or future session

If two copies differ, do not just update the currently active copy. Report the drift and either:

• update all authoritative/durable copies, or
• clearly mark which copy remains stale and what consequence that has.