# Llmdoc

> Default V3 operating skill for llmdoc-enabled projects. Route discovery — exploring the codebase, locating a concept or contract, judging the blast radius of a change — through the llmdoc CLI instead of broad file crawling.

- Skill: `tokenrollai/llmdoc` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add tokenrollai/llmdoc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tokenrollai/llmdoc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: TokenRollAI (https://skillmd.com/u/tokenrollai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tokenrollai/llmdoc

---


# /llmdoc

Use the CLI to retrieve durable architecture, constraints, and working agreements from V3 `llmdoc/` projects. Run commands as `npx -y @tokenroll/llmdoc <cmd>`.

## Retrieval Gate

Apply this gate before the first discovery action of a task, and again whenever investigation crosses into a new subsystem. Choose the one entry point that matches the intent:

| Intent | Entry point |
|---|---|
| Concept, contract, term, "where is X?" | `search <query>` |
| Background or blast radius of concrete source files | `context --files <path...>` |
| Cold start, unclear scope | `tree` |
| Known topic or document kind | `index --topic <topic>` / `--kind <kind>` |
| Bodies of documents already identified | `show <path...>` |

The gate guards broad native discovery: recursive or cross-directory exploration with Read, Grep, Glob, or shell outside a working set llmdoc has already narrowed.

Once llmdoc has narrowed that working set, native tools own the exact facts — source text, line numbers, test behavior, counts, git state. The knowledge surface deliberately does not duplicate those.

These entry points are alternatives, not a sequence. Stop as soon as the task has enough context; that permission applies after choosing an entry point, never instead of choosing one.

`status` and `delta` are not retrieval. Use them to assess staleness or to prepare `/llmdoc:update`, where `delta` decides light vs deep.

## CLI Invocation

`@tokenroll/llmdoc` is external tooling, not a project dependency. `-y` lets a missing package resolve into the npm cache without a prompt.

- Never add it to the served project's `package.json` or lockfile.
- Pin in the package spec when reproducibility matters: `npx -y @tokenroll/llmdoc@<version> <cmd>`.
- Never call a bare `npx llmdoc`; that name resolves to an unrelated package.
- If the CLI stays unavailable, report the degraded path, then continue with narrowly scoped native tools.

## Operating Rules

- Preserve and reuse `LLMDOC_STATE` across continuation; do not replay prior reads unless evidence changed or the task moved.
- Temporary investigation notes belong in `.llmdoc-tmp/`, not in stable docs.
- Stable `llmdoc/` writes belong to `recorder`; `llmdoc/meta.json` changes go through the CLI only (`new`, `adopt`, `mv`, `fingerprint`, `commit`). A valid `.mdx` that already exists on disk gets its ledger entry via `adopt <path...>` — never the delete-and-recreate dance through `new`.
- Before non-trivial edits, align with the user.
- If `llmdoc/` does not exist, suggest `/llmdoc:init`; do not fabricate the knowledge surface ad hoc.
- When a task produces durable knowledge changes, suggest `/llmdoc:update` at the end.
- For topology or routing work, read [Knowledge Topology](references/knowledge-topology.md).
- For SessionStart reminders or document preload, read [Startup Configuration](references/startup-config.md).
- Never suggest `/llmdoc:upgrade`; it runs only when the user asks for it by name.

## Reflection Gate

Strong reflection signals expose a reusable project or workflow lesson:

- the user corrects an assistant assumption or action
- verification proves the chosen approach wrong
- substantial rework, rollback, or an instruction violation occurs
- a missing project signal would likely prevent recurrence

Skip transient tool failures, trivial typos, speculation, and one-task preferences unless marked durable.

On a strong signal, continue the task and give `reflector` compact evidence while context is fresh. It writes a privacy-safe candidate under `.llmdoc-tmp/reflections/pending/`, never the transcript or tracked knowledge. A pending candidate triggers update review even with no source delta. At task end, name the lesson and ask once to run `/llmdoc:update --reflection <path>`; wait for authorization.

## Continuation State

On compact or resume, keep `LLMDOC_STATE` small and practical:

- active goal
- documents already read
- key conclusions and invariants
- user decisions and constraints
- next action
- open risks or unknowns
- pending lesson candidates, if any

If that state is still sufficient, continue without re-running `tree`, `index`, or prior `show` reads.

## Roles

- `investigator`: current-state research, scoped evidence gathering, scratch reports under `.llmdoc-tmp/`
- `reflector`: turns strong corrections, verified mistakes, and major rework into structured candidates under `.llmdoc-tmp/reflections/pending/`
- `recorder`: the only writer of tracked `llmdoc/` knowledge