doc-indexer

What this skill does

# Document Indexer Skill

## Purpose

Provide just-in-time context about available project documentation without loading full file content into the context window. The doc-indexer scans all markdown files in the `docs/` directory, extracts their YAML frontmatter metadata, and returns a structured map of available documentation. This enables efficient discovery of specs, plans, retrospectives, and other documentation while minimizing token usage.

## When to Use

Use this skill in the following situations:

- At the beginning of any work session to understand the current state of documentation
- When starting work on a new issue to identify relevant specs and context
- Before proposing changes to understand existing specifications
- When planning a sprint to review available approved specs
- Anytime you need an overview of project documentation without reading full files

## Prerequisites

- The project must have a `docs/` directory
- Documentation files should follow the convention of including YAML frontmatter
- The `jq` tool is NOT required (script works without it)

## Workflow

### Step 1: Run the Documentation Scanner

Execute the helper script to scan all markdown files in the docs/ directory:

```bash
bash scripts/scan-docs.sh
```

This will output a human-readable summary showing each document's frontmatter metadata.

For machine-readable JSON output (useful for programmatic processing):

```bash
bash scripts/scan-docs.sh -j
```

### Step 2: Review the Documentation Map

The scanner returns information about all markdown files found in `docs/`, including:

- **File path**: Location of the documentation file
- **Frontmatter metadata**: Key-value pairs from YAML frontmatter (title, status, type, etc.)
- **Compliance warnings**: Files missing YAML frontmatter are flagged

**Example human-readable output**:
```
---
file: docs/specs/001-synthesis-flow.md
title: AgenticDev Methodology
status: approved
type: spec
---
file: docs/changes/my-feature/proposal.md
title: My Feature Proposal
status: in-review
type: proposal
[WARNING] Non-compliant file (no frontmatter): docs/README.md
```

**Example JSON output**:
```json
[
  {
    "file": "docs/specs/001-synthesis-flow.md",
    "compliant": true,
    "frontmatter": {
      "title": "AgenticDev Methodology",
      "status": "approved",
      "type": "spec"
    }
  },
  {
    "file": "docs/README.md",
    "compliant": false,
    "frontmatter": null
  }
]
```

### Step 3: Use the Map to Identify Relevant Documentation

Based on the documentation map, identify which specific files to read for your current task:

- **For implementation work**: Look for approved specs related to your issue
- **For spec proposals**: Review existing specs to understand the current state
- **For sprint planning**: Identify approved specs ready for implementation
- **For learning context**: Find retrospectives and design docs

### Step 4: Read Specific Documentation Files

Once you've identified relevant files from the map, use the Read tool to load their full content:

```bash
# Example: Read a specific spec identified from the map
Read docs/specs/001-synthesis-flow.md
```

This two-step approach (scan first, then read selectively) minimizes token usage while ensuring you have access to all necessary context.

## Error Handling

### No docs/ Directory

**Symptom**: Script reports "No such file or directory"

**Solution**:
- Verify you're in the project root directory
- Check if the project has been initialized with `project-init` skill
- Create `docs/` directory structure if needed

### Files Missing Frontmatter

**Symptom**: Script outputs "[WARNING] Non-compliant file (no frontmatter): ..."

**Impact**: These files won't have structured metadata in the output

**Solution**:
- Add YAML frontmatter to documentation files for better discoverability
- Frontmatter should be at the top of the file between `---` markers
- Example format:
  ```markdown
  ---
  title: My Document
  status: draft
  type: design
  ---

  # Document content starts here
  ```

### Script Permission Errors

**Symptom**: "Permission denied" when running the script

**Solution**:
```bash
chmod +x scripts/scan-docs.sh
```

## Output Interpretation Guide

### Frontmatter Fields

Common frontmatter fields you'll encounter:

- **title**: Human-readable document title
- **status**: Document state (draft, in-review, approved, archived)
- **type**: Document category (spec, proposal, design, retrospective, plan)
- **epic**: Associated epic issue number
- **sprint**: Sprint identifier
- **author**: Document author
- **created**: Creation date
- **updated**: Last update date

### Using JSON Output Programmatically

The JSON output mode is particularly useful when:

- Filtering documents by specific criteria (e.g., only approved specs)
- Counting documents by type or status
- Building automated workflows
- Integrating with other tools

Example using `jq` to filter approved specs:
```bash
bash scripts/scan-docs.sh -j | jq '.[] | select(.frontmatter.status == "approved")'
```

## Notes

- The scanner is non-invasive and read-only - it never modifies files
- Large projects with many docs benefit most from this just-in-time approach
- The script scans recursively through all subdirectories in `docs/`
- Empty frontmatter sections are treated as non-compliant
- The scan is fast and can be run frequently without performance concerns
- Consider running this at the start of each work session to stay current with documentation changes