---
name: simplicio-mapper
description: Survey and understand Simplicio codebases before action. Use for repository discovery, architecture mapping, symbol and dependency lookup, call-graph analysis, precedent search, snapshot creation, context selection, and any task where an agent must understand the project before editing. Do not use it as the mutation owner.
---

<!-- simplicio-contract:begin -->
contract: simplicio-mapper
schema: simplicio.skill/v1
purpose: Survey and understand Simplicio codebases before action.
rules: Follow this skill end-to-end; mutable data (versions, dates, counts) lives in the footer, never in this header.
<!-- simplicio-contract:end -->

# Simplicio Mapper

Use Mapper as the canonical SURVEY and context-selection layer. Produce a bounded, reproducible project snapshot before any non-trivial change. Read `references/capabilities.yaml` for the complete capability catalog and `references/interfaces.md` for interface-specific details.

## Complete interface map

When documenting or invoking a concrete Mapper release, use the Prism inventory generator to record CLI, MCP, Python, Rust, configuration, I/O, effects, errors, fallbacks, dependencies, cost, version, and compatibility. Treat static inferences as review-required until validated.

## Routing

- Invoke for `mapear`, `entender`, `localizar`, `impacto`, `dependências`, `precedente`, `call graph`, `snapshot` or context selection.
- Invoke before Dev CLI mutations unless a fresh compatible snapshot is already available.
- Add Fast when the query is repeated, broad, or latency-sensitive and a compatible index exists.
- Do not edit files, invent missing symbols, or claim that a snapshot proves behavior.
- If Mapper is unavailable, use the smallest read-only native fallback and mark the result `survey-degraded`.

## Required workflow

1. Resolve repository, revision, scope, and requested intent.
2. Reuse a fresh snapshot only when repository revision and scope match.
3. Run the narrowest survey that answers the request.
4. Return evidence locations, uncertainty, and the snapshot identifier.
5. Hand the snapshot and selected context to Dev CLI, Loop, or Prism.

## Contract

Return `snapshot_id`, `repo`, `revision`, `scope`, `artifacts`, `selected_context`, `unresolved_questions`, and `verification`. Keep context minimal; never paste an entire repository when a symbol/file slice is sufficient.

## Resources

- `references/capabilities.yaml`: machine-readable capability map.
- `references/interfaces.md`: inputs, outputs, freshness, and fallbacks.
- `scripts/probe-capabilities.py`: validate the capability manifest and detect duplicate IDs.

## Runtime integration boundary (normative, 2026-08-05)

Mapper is a peer route for project-scoped context and remains read-only. Runtime
may select it for a project edit before the direct `simplicio edit` mutation.
Standalone Mapper use remains valid without Runtime, Loop, or a cross-component
contract. Handoffs used by Fast or Loop must be fresh, complete, unlocked, and
revision-compatible.

## What the model sees

When a host loads this skill, the model receives the YAML frontmatter, the
immutable `simplicio-contract` header, and this body, verbatim. Files under
`references/` enter the context only when this body points to them. Nothing
here is generated per run.

### Token effect

The body is paid once per session as input tokens. References are paid only on
demand, so the always-loaded part stays the short hot path.

### KV cache effect

The frontmatter and header are byte-stable across releases (pinned in
`contracts/headers.lock.json`), and mutable data lives only at the end of the
file. The provider can therefore reuse the cached prefix from the second call
on, and a release does not invalidate it unless a `header-change:` note says so.