Use the workflow that serves the request. Investigation is the default; documentation, startup repair, tests and modernization are optional. A broken build does not turn an investigation into a repair task.

Start with direct search for a known path or symbol; no setup or saved map is needed. For an unfamiliar subsystem, use one native scoped map and original source. For several modules or repeated difficult questions, follow scale and intake: lazy catalogs, one task map and evidence-based optional pilots. Large size alone does not require retrieval. The bundled tools are bounded and have not been validated on a hundreds-of-megabytes production corpus.

Use the native Rust mapper

legacy-repo-map

for repository maps by default. A normal skill installation includes its setup script, pinned policy, source, queries and notices, not executables. Verify local readiness first; downloading a prebuilt program needs no Rust compiler or Python parser packages. Read binary delivery only for platform limits or publishing details.

Native setup contract: pins from and names the Windows x86-64, Linux x86-64 and macOS ARM64 archives. WSL uses the Linux archive. First run:

python /path/to/skill/scripts/setup_native.py status

If it returns , use the returned path. For , run ; it selects and verifies the pinned platform release automatically. If the pinned release is unavailable, follow the explicit reviewed CI/local-package route in native setup. Do not search “latest,” build Rust implicitly, or substitute an old 0.1.0 artifact. Use the Python fallback only when native installation/execution is unavailable, the OS is unsupported or policy blocks it, or exact reference behavior is required.

Do not write machine-specific "ready" or "to do" state into this installed . The setup script revalidates the machine-local receipt, package hashes and binary version before reporting readiness. Native remains experimental: grammar/query coverage and consumer execution limits still apply; see native tooling when comparing behavior.

Report destination: honor the user's path; otherwise, when repository writes are authorized, save readable results under , with a descriptive name such as . Announce the destination before generation and link the exact saved files afterward. For read-only work, use an authorized external artifact location. Ask only when the destination cannot be inferred, would overwrite existing work, or conflicts with repository instructions. Keep corpus/module names distinct when comparing several maps.

The low-level mappers require an external output/cache directory and use fixed filenames. Generate there, then use to save a named report, raw map and evidence sidecars at the chosen destination. Exported reports include coverage, truncation, token estimates and measured elapsed time when supplied. Keep the primary overview and optional complete-definition index in the chosen report directory; the exporter places raw maps/inventory/metadata under its subdirectory. Historical comparisons and review evidence belong there too. Keep private maps local and Git-ignored; verify they are absent from publishable history before pushing. See repository maps for commands and timing rules. Exclude saved reports from later root scans so generated context does not map itself; do not commit generated maps unless requested or appropriate to the task.

The native map runs locally without an LLM endpoint. It parses source with Tree-sitter, ranks identifier relationships using an adaptation of Aider's repo map, and selects definitions within a declared budget. It is navigation, not a type-resolved call graph or a substitute for method bodies. Attribution and licenses are in THIRD_PARTY.md.

Read setup and distribution for first-time installation or standalone executables. Read repository maps for CLI options, metadata and citation checking.

After setup, run the verified path returned by status, with an artifact directory outside the source repository:

/path/returned/as/program /path/to/repository --output-dir /path/to/artifacts --budget 16384

Map the relevant subtree when the repository is large. Repeat for one active-task map across modules and the required core slice; keep separate reusable module indexes only when useful. Keep generation staging and caches outside the source tree; export requested readable reports to the announced destination.

Read its scope, revision, omitted-definition count and clipping records. The default grouped format provides file/class context and multiline declarations, with reported 80-line/8,000-character snippet bounds. The default map budget is 16,384 estimated tokens. Increase for a broader overview, or use with a sufficient budget for an index of every captured definition in the selected scope; the latter fails instead of quietly returning a partial index. Neither mode resolves runtime behavior or unsupported constructs.

When repository instruction edits are authorized, add or update one concise pointer in the existing section: name the overview, its scope, when to read it, and the complete index for deeper symbol lookup. Preserve the surrounding instructions. Read relevant original bodies and callers before making changes or writing behavior documentation. Refresh the map and pointer when paths, declarations or examined scope change. See using the map for the task.

Load only the reference that matches the task. Do not install every optional tool or generate a full documentation set for a small question.

For a consequential claim, record the file and original line range, source hash/revision, a short supporting quotation, and whether the claim is observed or inferred. Include unknowns and the next source needed to resolve them. Generated documentation should preserve these links and the examined revision so it can be refreshed after changes.

For framework APIs, find the definition plus a real caller, test or configuration example. Verify parameter types, lifecycle, side effects and error handling from those sources. Do not invent a familiar public API for an unfamiliar private framework. When evidence is missing, search or ask for the missing source rather than filling the gap.

The citation checker can detect fabricated or stale references. It cannot establish that a claim follows from its quotation; read the cited code and wiring to verify that.