Index Navigator

Index Navigator

Overview

Navigate catalogador-generated index.md files to determine which documents or sections to read, minimizing unnecessary context consumption. Output the stdout 📚 index-navigator invocado na pasta: <PASTA> before any other action.

When to Invoke

Invoke this skill immediately when:

1. Attempting to read any document within a directory containing index.md
2. Listing a directory and finding index.md among the files
3. Exploring a folder structure where index.md exists

Rule of thumb: If index.md exists in the target directory, use it as a navigation guide before reading any other file.

First Action: stdout

Before performing any reads or navigation, output a single-line log to the terminal:

📚 index-navigator invocado na pasta: <PASTA>

Determining <PASTA>:

• If triggered by reading a document: use the document's directory path
• If triggered by listing a directory: use that directory path

Mental Model

Treat each index.md as a menu that:

• Lists available files and subdirectories
• Indicates when to use or ignore each item
• Provides quick navigation paths (links/anchors)
• Often includes token cost estimates per section

Golden Rule: Read index.md first. Read complete documents only when necessary.

Reading index.md Files

When opening an index.md, extract only these sections:

1. Navegação Rápida (Quick Navigation)

• Maps "want X → read Y" directly
• Prefer this path when it matches the request

2. Arquivos (Files)

For each file, focus on:

• Objetivo principal (Main objective)
• Use quando (Use when)
• Não cobre (Does not cover)
• Estrutura (Structure: anchor links + token estimates)

3. Subpastas (Subdirectories)

For each subdirectory, focus on:

• Resumo (Summary)
• Quando explorar (When to explore)
• Quando ignorar (When to ignore)

4. Escopo (Scope)

Determines whether this directory is relevant for the current task.

Ignore other sections unless needed for disambiguation.

Navigation Workflow

Step 1: Choose Initial index.md

• If triggered in a specific directory, start with that directory's index.md
• If multiple indices exist, prefer:
  1. Current directory's index.md (where exploring)
  2. Parent index.md if current is too narrow

Step 2: Decide Navigation Path Using index.md

Decision order:

1. Navegação Rápida contains the answer → follow indicated link
2. Otherwise, use Arquivos:
   • Select file whose Use quando best matches the request
   • Respect Não cobre (if it falls there, wrong file)
3. If correct file not listed, use Subpastas:
   • Enter only subdirectories marked Quando explorar that match the case
   • Avoid those indicating Quando ignorar for this scenario

Step 3: Navigate Levels if Stuck

• Index too general and doesn't point to target → descend to subdirectories
• Index too specific and doesn't mention topic → ascend to parent index

Reading Strategy: Section vs Complete Document

When index.md offers anchors/sections, apply these rules:

Read ONLY A SECTION when

• Request is specific
• Index already points to a corresponding anchor
• Section is visibly smaller than total document
• File has well-defined Estrutura (clear headings)

Read COMPLETE DOCUMENT when

• Request is broad and requires full view
• Index doesn't offer useful anchors (or no clear headings)
• Answer depends on multiple scattered sections (≥3) and sum approaches total
• File is explicitly "foundational" (overview/architecture/cross-cutting) and request depends on global understanding
• Total estimated tokens are small (e.g., ≤ ~1200–1500 tokens) and reading entire reduces risk of missing context

Decision Heuristic

If index provides tokens per section:

• 1 section resolves → read 1 section
• 2 sections resolve → read 2 sections
• 3+ sections needed and sum > ~60% of total → read complete document

If NO token estimates:

• Prefer section if clear anchor exists
• If need to hunt across multiple headings → read complete document

Assertive Reading Without Overreading

Before opening a complete document, answer internally:

1. "What exact question does this file answer?"
2. "Is there a section/anchor that already delivers this?"
3. "How many sections do I actually need?"

If unable to answer (1) based on the index, likely in the wrong index (ascend/descend and try another).

Expected Output

Produce for the agent a short list (1–5) of recommended reads, each containing:

• Path: File path
• Target: section/anchor OR complete document
• Reason: Single sentence referencing "Use quando / Não cobre / Navegação rápida"

Example:

1. docs/sso/auth0-setup.md#token-generation (section)
   Reason: "Use quando" indicates this section covers token generation workflows.

2. docs/techspec-backend.md (complete document)
   Reason: Request requires understanding of full backend architecture; multiple sections needed.