Skip to content
Skills Library
Programming · Analysis

index-code

/index-code

[Orbit 1.2.2 Code recon] Working code index: index first, then targeted reading — fewer tokens and calls. Use when: «где это в коде», «кто вызывает», «найди все места», «где используется», «проиндексируй код»; where is, callers, find usages.

Licence
MIT
Last repository change
09.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

[Orbit 1.2.2 Code recon] Working code index: index first, then targeted reading — fewer tokens and calls. Use when: «где это в коде», «кто вызывает», «найди все места», «где используется», «проиндексируй код»; where is, callers, find usages.

Original author description

[Orbit 1.2.2 Code recon] Working code index: index first, then targeted reading — fewer tokens and calls. Use when: «где это в коде», «кто вызывает», «найди все места», «где используется», «проиндексируй код»; where is, callers, find usages.

How it works

  1. When to use
  2. Inputs
  3. Procedure
  4. Output
  5. Check
  6. Pitfalls
  7. Portability
  8. What's improved vs the source
  9. Based on
Original SKILL.md headings · 164 lines, 1,264 words
SKILL.md preview
---
name: index-code
description: '[Orbit 1.2.2 Code recon] Working code index: index first, then targeted reading — fewer tokens and calls. Use when: «где это в коде», «кто вызывает», «найди все места», «где используется», «проиндексируй код»; where is, callers, find usages.'
---

# index-code — index first, then read

> **Orbit · ① Understand · step 1.2.2 Code recon**
> **Input:** repository
> **Output:** `.orbit/knowledge/index/` → next `explain-code`
> **Works with:** `map-knowledge`, `trace-impact`, `explain-code`
> **Shared rules:** reply in the user's language per `speak-plain`; generated content defaults to English; act within `stay-in-scope`; artifacts go to `.orbit/` (contract: `ARTIFACTS.md`).

Method of Graft / Trail-code: ask a **code index** before reading sources — fewer tool calls
and tokens. Rewritten for built-in tools. If the `trail`/`graft` CLI is installed
(`npm i -g @trailhq/trail-code`), use it: `graft ask`, `graft grep`, `graft skeleton`,
`graft callers` do the same faster. Without it, the index is built from `grep` and short notes, as below.

## When to use

- Any question shaped as "where is X", "who calls Y", "every place Z is used".
- Before opening files in a repository you have not indexed yet — the first full-file
  read is what the index exists to avoid.
- A change is about to touch a symbol and you need its consumers before editing.
- An answer from a previous search was weak and the temptation is to search again in
  other words.
- After a significant change, to keep the index and its wiring current.

Skip for a repository of a few files, or when you already have the exact `file:line` —
read that range and answer.

## Inputs

- The repository and its file list: `git ls-files | head -200`, `wc -l <(git ls-files)`.
- The question in the user's words and the short symbol name behind it.
- An existing graph, if `map-knowledge` ran: `.orbit/knowledge/graph.json` — reuse its
  nodes instead of re-deriving them.
- Any previous index: `ls .orbit/knowledge/index/` (skeleton, nodes, wiring).
- The build/test entry points for context: `package.json`, `go.mod`, `pyproject.toml`,
  `Makefile`.

If no index exists, build the three parts below before answering; if only a graph
exists, skip the node inventory and generate skeleton and wiring from it.

## Procedure

1. **Take the question and reduce it to one symbol or one path.** "Where is the CSV
   export?" → `exportCsv` or `src/export/`. If the question contains several questions,
   answer them one at a time with the matching move.
2. **Build the file skeleton — signatures without bodies.** One command, saved to
   `.orbit/knowledge/index/skeleton.txt`:

   ```bash
   grep -rnE '^\s*(export\s+)?(async\s+)?(function|class|def|func|interface|type|public|private|internal)\b' src/ > .orbit/knowledge/index/skeleton.txt
   ```

   For a large codebase, run it per area (`src/api`, `src/domain`).
3. **Write node notes, one file per area.** `.orbit/knowledge/index/nodes/<area>.md`:
   3–8 lines of prose — "what's here and why" — plus exact `file:line` ranges. One node
   note is enough to answer most "where" questions without opening the code.
4. **Map the wiring for key symbols.** For each symbol that matters in this task:
   `grep -rn '\b<SymbolName>\b' src/` → add a line to
   `.orbit/knowledge/index/wiring.md` in the form `A → B (file:line)`. Wiring is the
   caller graph; it is what makes "what breaks if Z changes" answerable.
5. **Pick exactly one move per question.** Do not chain searches "just in case":

   | Question | Move |
   |---|---|
   | "How does X work / where is X?" | find the node, read the listed lines (offset + limit) |
   | "Every place Y is used" | one `grep -rn` on the short name, not a full signature; empty → loosen the pattern |
   | "API of a file" | skeleton or `grep -n` on signatures in that file |
   | "What breaks if Z changes" | wiring: all callers of Z and their callers (2 levels) |

6. **Don't re-ask the same question in other words.** If the first move is weak, change
   the move (skeleton → grep → wiring), not the wording. A second paraphrase of the same
   search returns the same noise.
7. **Verify the index.** Every `file:line` in a node note resolves (`sed -n '<line>p' <file>`);
   every wiring line has both ends and the evidence path; the skeleton has no duplicate
   areas. Fix what does not resolve — a stale index is worse than none.
8. **Keep it fresh.** After a significant change, update the affected nodes and wiring in
   the same loop as `run-spec-loop`. The index is derived: commit it only by agreement
   (`stay-in-scope`), otherwise keep it in the `.orbit/` work folder.

## Output

`.orbit/knowledge/index/` — a working index with three parts:

```text
.orbit/knowledge/index/
  skeleton.txt          signatures with file:line, no bodies
  nodes/<area>.md       3–8 lines per area + exact ranges
  wiring.md             A → B (file:line) caller edges
```

Node note example:

```markdown
# nodes/export
The CSV export path: HTTP handler → query → stream. No PDF, no scheduled mail.
- handler: src/export/router.ts:20-60
- query: src/reports/query.ts:88-140
- stream helper: src/http/files.ts:42-75
```

Wiring example:

```text
router.get('/reports/orders.csv') → exportOrders (src/export/router.ts:31)
exportOrders → buildOrdersQuery (src/reports/query.ts:90)
exportOrders → sendFile (src/http/files.ts:44)
```

## Check

Before answering, or before calling an index refresh done:

```bash
ls .orbit/knowledge/index/skeleton.txt .orbit/knowledge/index/wiring.md
grep -c ':' .orbit/knowledge/index/skeleton.txt        # skeleton lines carry file:line
grep -c '→' .orbit/knowledge/index/wiring.md           # edges exist
for f in .orbit/knowledge/index/nodes/*.md; do grep -Hn ':[0-9]' "$f"; done
git status --short .orbit/                             # index is not staged by accident
```

Pass rule: for every question the index answers, the answer cites a `file:line` that
resolves; the skeleton and wiring files exist and are non-empty; each node note has at
least one range; no answer required a full-file read outside the listed ranges; the
index is refreshed after the last significant change. If a `file:line` is stale, fix the
index before using it.

## Pitfalls

- **Reading full files "to be sure".** That is the cost the index exists to avoid. Read
  the listed range; widen only when the range does not answer the question.
- **Indexing everything before answering.** A full index of a huge repo takes longer than
  the question. Index the area the question touches first.
- **A skeleton that silently skips a language.** The regex covers common `function/class/
  def/func` forms; if a language is missing, add its keyword before trusting the file.
- **Wiring without evidence.** `A → B` with no `file:line` is a guess; it will be wrong
  in exactly the case that matters (a dynamic call, a re-export).
- **Stale index after a rename.** A moved symbol leaves a dead `file:line` and wrong answers. Refresh after changes.
- **Re-searching the same question in new words.** The second search returns the same
  results and burns context. Change the move, not the phrasing.
- **Committing the index without agreement.** It is a derived work folder, not source;
  decide with the team before it enters the repository.

## Portability

No Claude-only feature: `grep`/`rg`, `sed`, `git` and a text editor suffice; `npm i -g
@trailhq/trail-code` is optional and only an accelerator. On any CLI, the same three
files can be built with `grep` and written by the agent's file tools. Without subagents,
build one area at a time inline. If `graft` is available, its `ask`/`grep`/`skeleton`/
`callers` output maps one-to-one onto the "one move per question" table. The index stays
under `.orbit/knowledge/index/` in every agent, so `explain-code` and `trace-impact`
read the same artifact regardless of who built it.

## What's improved vs the source

- "Index first" works without the npm CLI: index from `grep` plus short node notes; the CLI is used when present.
- A "question type → one move" table instead of chains of searches.
- Index refresh is part of the same loop as spec and map.
- Every node and wiring line must resolve to a `file:line`, with a verification step.
- The index is explicitly a derived work folder: commit only by agreement.

## Based on

- [Graft / Trail-code](https://github.com/trailhq/Graft) — method «graft» (MIT). Rewritten in our own words and improved — see "What's improved".

Versions

The database has no other skills named index-code.

Database snapshot: 13.11.2026 · package version db7f1c621533 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100code-search
    Search for patterns inside file contents using ripgrep (rg). Use when searching for code patterns, finding function definitions, locating usages, or when the user asks to search/grep content inside files.
  • 100codeindex
    Navigate a git repository with the codeindex index before grepping or reading whole files. Use when you need to find where a Python/JS/TS symbol, config key or environment variable is defined, who calls a function, which tests cover a file, what a change may break, or a compact…
  • 100trace-impact
    [Orbit 1.2.5 Code recon] What a change touches: affected modules, consumers, external contracts, risk level. Use when: «что сломается», «радиус изменения», «на что влияет MR», «кто это использует», «оцени риск изменения»; impact analysis, blast radius.
  • 100github-code-search
    Use when you need real-world implementation examples or cross-repository context — search GitHub's global code index with the built-in MCP tools and reuse the results as grounded context.
  • 100recall-history
    [Orbit 1.2.6 Code recon] Recall past work: memory, .orbit/learnings, ADRs, git, past sessions, MRs. Use when: «что мы уже делали», «вспомни», «было ли такое», «мы это уже пробовали», «найди прошлое решение»; recall, what did we do before.
  • 85unity-skills-index
    Index of all Unity Skills modules with per-module mode labels (SA/FA/Mixed). Use to find which module covers a task before loading its doc.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.