dekko-orient git:20260803.ca49afcA

Immutable. This exact content is served forever at /api/v1/blob/93a3dfd6b4d5fcb9.

---
name: dekko-orient
description: Use dekko's tools instead of grep/Read whenever a repo has a .dekko/ directory — not just at session start. Trigger on any "find/locate/understand this symbol," "what does this file/dir contain," "what will this change break," or "read this file" impulse. dekko has already parsed and indexed the repo; grepping or reading whole files re-does work dekko already did, at higher token cost.
---

# Orienting with dekko (read less of the repo)

A repo with a `.dekko/` directory is already parsed and indexed. Call
dekko's MCP tools (`mcp__dekko__*`) or CLI **before** grepping for a
symbol or reading a whole file — that is the token cost this skill
exists to avoid. If `mcp__dekko__*` tools don't show up in your
toolset yet, they may be deferred behind a tool search — search for
"dekko" before falling back to Read/Grep, don't give up after one miss.

No `.dekko/` directory yet? Run `dekko map .` (or the `/map` command)
once, then use the tools below.

## When to reach for dekko vs. grep/Read

| Need | Use | Not |
|---|---|---|
| A symbol's signature, doc, or its callers/callees | `query_symbol`, `get_callers`, `get_callees` | grep for the name |
| A file or directory's shape | `outline` | reading the whole file |
| Everything needed to work a diff or symbol | `workset` | assembling outlines + packs by hand |
| Tests a change impacts | `impacted_tests` | guessing from filenames |
| Text dekko doesn't model — strings, comments, config, prose | grep/Read | — |

## Orient first

```
mcp__dekko__summary          # MCP tool — capped at ~2000 tokens by default
dekko orient                 # CLI — same digest + steering preamble, capped at ~1500 tokens
```

Names every directory's purpose, load-bearing/orchestrating symbols,
entrypoints, and largest files in a few hundred tokens.

Caution: bare `dekko summary` (CLI, no `--budget`) and the raw
`dekko://summary` MCP resource are **unbounded** — a large repo's
digest can run ~30k characters. Call the `summary` tool, `dekko
orient`, or pass `--budget` explicitly instead.

## Read less of the repo

```
mcp__dekko__outline <file-or-dir>     # or: dekko outline path/to/file.py
```

Module doc + every symbol's signature, first doc line, and line
number — no bodies, ~1/10 the cost of a full read. A directory target
rolls up its files.

```
mcp__dekko__workset                   # or: dekko workset [REV] | dekko workset --symbol NAME
```

One budgeted bundle for a change or symbol: impacted tests +
touched-file outlines + call-graph packs for the most central touched
symbols — replaces assembling `affected` + N outlines + N packs by
hand.

```
mcp__dekko__query_symbol <sym>        # or: dekko query symbol <sym>
mcp__dekko__get_context_pack <sym>    # or: dekko context <sym>
mcp__dekko__get_callers <sym>         # or: dekko query callers <sym>
mcp__dekko__get_callees <sym>         # or: dekko query callees <sym>
mcp__dekko__impacted_tests [REV]      # or: dekko affected [REV]
```

`query_symbol` gives signature/doc/fan-in-out at a glance;
`get_callers`/`get_callees` give the actual exact call edges (unlike
grep, which can't tell a call from a same-named string) — use them
for impact analysis before a change. `get_context_pack` bundles a
symbol's neighborhood in one budgeted pack.

Targets accept a bare name, `Class.method`, `file.py:name`, or the
`file.py::name` / `Class::method` form (the C++/Rust habit) — all
resolve to the same symbol.

## Boundaries

- Structural aids, not a substitute for reading the exact lines you
  are about to edit — outline/query to navigate, read to edit.
- Stateless: re-run when you need it; a digest doesn't track edits
  made after it was generated.
- Most tools take a `budget`/`--budget`; the footer reports token cost
  and what was dropped to fit.
- `get_callers` hides test-file callers by default (`include_tests`
  to include them) — an empty result doesn't mean dead code.
- Shortest call path between symbols, dead-code leads, hotspot
  stats, and the terse "lean" map are **CLI-only** — no MCP tool
  exists for them; use Bash: `dekko trace|unused|stats|lean ...`.