tour

Files (1)

• SKILL.md

SKILL.md (first lines)

# tour — Lightweight read-only orientation

You are operating in **reader-first** mode. Your job is to map and explain
code, not to change it. This skill is the **single-session sibling** of
`/grok-codebase` — when the user wants orientation, not memorization.

## When to use this vs `/grok-codebase`

| `tour` (you) | `grok-codebase` |
|---|---|
| Single session, answer-and-stop | Multi-session, persists artifacts |
| Layered summary (purpose → modules → call graph) | Four-pillar march (Building Blocks → Entry Points → Infrastructure → Egress) |
| No quiz | Adaptive Socratic quiz at the end |
| ≤ 10k tokens of tool output | Up to 30k tokens |
| Triggers: "tour", "where is X", "how does Y work" | Triggers: "grok", "onboard me", "memorize this" |

If the user's phrasing is ambiguous, ask: *"Quick tour, or full grok with
quiz at the end?"*

## Instructions

### 1. Anchor on entry points first

Find `main`, `index.ts`, `app.py`, route files, CLI entrypoints. Use
Serena (`find_symbol`, `get_symbols_overview`) — it's faster than
`read_file`. If the user pointed at a specific feature or file, anchor
on **that** instead and walk outward.

### 2. Build a layered summary

- **Top layer** — one-paragraph project purpose, inferred from
  `README.md` + the primary manifest (`package.json` / `pyproject.toml`
  / `go.mod` / `Cargo.toml` / `pom.xml`).
- **Middle layer** — module map. For each top-level source dir,
  one line: *what role does this dir play?* Use
  `mcp__serena__get_symbols_overview` per dir.
- **Bottom layer** — for the file or feature the user pointed at, a
  function-level call graph. Use `mcp__tilth__tilth_grok(target=<symbol>)`
  for one-shot def + body + callers + callees + tests.

If the user didn't point at anything specific, ask: *"Which feature or
file do you want the bottom layer on?"* Don't guess.

### 3. Cite every claim

Every claim about the code must include a `path/to/file.ts:line`
citation. **Never paraphrase without a citation.**

### 4. MCP tool priority order

In rough order of efficiency:

1. `mcp__serena__find_symbol` / `find_referencing_symbols` — symbol
   navigation
2. `mcp__serena__get_symbols_overview` — file outlines
3. `mcp__tilth__tilth_grok` — one-shot deep dive on a symbol
4. `mcp__tilth__tilth_search` — text/content fallback
5. `mcp__tilth__tilth_deps` — call/import relationships
6. `mcp__context7__query-docs` — only when the user asks about an
   external library's API
7. `@codebase` / `codebase_search` — last-resort semantic search

### 5. Stop conditions

- **Stop after you've answered.** Do not volunteer refactors, risks,
  or "while we're here" suggestions.
- If the user asks "what should we change?", switch out of tour
  mode and ask for explicit permission to propose edits.
- If the tour scope grows past 10k tokens of tool output, summarize
  and ask: *"Want to keep going, or switch to `/grok-codebase` for
  the full multi-phase run?"*

## Examples

✅ Good

> The auth flow starts at `src/api/auth/login.ts:42` (`handleLogin`),
> calls `verifyCredentials` in `src/services/auth.ts:88`, which uses
> bcrypt via `src/lib/crypto.ts:12`. The token is signed in
> `src/lib/jwt.ts:31` and persisted to Redis via
> `src/lib/session.ts:55`.

❌ Bad

> It looks like a standard auth flow. You should probably add rate
> limiting.

❌ Bad

> The auth code is in `src/auth/`. (paraphrase, no specific
> file:line, no causal chain)

## Output template

```
## Top — what this project is
<one paragraph>

## Middle — module map
- `src/api/` — HTTP route definitions and request validators
- `src/services/` — business logic, framework-free
- `src/lib/` — shared utilities (crypto, jwt, redis client)
- ... (one line per top-level dir)

## Bottom — <feature or file the user asked about>
<function-level call graph, file:line cited on every node>
```

## Conventions

- **Read-only verbs only**: `read_file`, `codebase_search`,
  `find_symbol`, `mcp__serena__*`, `mcp__tilth__*` (except
  `tilth_write`), `@codebase`, `@docs`, `@web`.
- **Forbidden until explicitly invited**: `edit_file`, `write_file`,
  `mcp__tilth__tilth_write`, `run_terminal_cmd` (except read-only
  commands like `git log`, `git status`, `git diff`, `ls`, `wc`).
- **No persistence**. Unlike `/grok-codebase`, `tour` does NOT write
  artifacts to disk. If the user wants the tour saved, suggest
  `/mental-model` to seed `docs/mental-model.md` themselves.

From paulnsorensen/dotfiles, MIT.

More from paulnsorensen/dotfiles