doc-navigator

name	doc-navigator
description	Efficiently navigate codebase documentation during Research phase. Use instead of Grep/Glob for finding architectural decisions, feature specs, and technical docs. Maps topics to doc locations for fast context retrieval. If codebase lacks documentation structure, provides patterns to establish one.

Doc Navigator

Navigate codebase documentation efficiently by checking known doc locations first, before resorting to grep/glob searches.

When to Use

• Finding architectural decisions (ADRs)
• Locating feature specs or API docs
• Researching codebase before implementation
• Suggesting documentation structure for new projects
• Alternative to grep/glob for doc discovery

Quick Start

1. Check for docs directory at project root
2. Scan for common doc file patterns
3. If docs exist → map topics to locations
4. If no docs → suggest documentation structure (see references/doc-patterns.md)

Common Documentation Locations

Check these locations in order:

project-root/
├── docs/                    # Primary documentation
│   ├── architecture/        # System design, ADRs
│   ├── features/            # Feature specs
│   ├── api/                 # API documentation
│   └── guides/              # How-to guides
├── .github/                 # GitHub-specific docs
│   └── docs/
├── README.md                # Project overview
├── ARCHITECTURE.md          # High-level architecture
├── CONTRIBUTING.md          # Contribution guidelines
└── doc/ or documentation/   # Alternative doc folders

Topic-to-Location Mapping

Looking for...	Check first
Project overview	README.md
Architecture/design	docs/architecture/, ARCHITECTURE.md, docs/adr/
Feature specs	docs/features/, docs/specs/
API reference	docs/api/, api-docs/, OpenAPI/Swagger files
Setup/installation	docs/guides/setup.md, INSTALL.md
Database schema	docs/database/, docs/schema/, prisma/schema.prisma
Data types/models	docs/types/, docs/models/, src/types/, src/models/
Style guide	docs/style-guide.md, docs/conventions.md, .eslintrc, STYLE.md
Environment config	docs/config/, .env.example, docs/environment.md
Testing strategy	docs/testing/, tests/README.md
Deployment	docs/deployment/, docs/infrastructure/
ADRs (decisions)	docs/adr/, docs/decisions/, architecture/decisions/
ADRs (fallback)	CHANGELOG.md, git log, PR descriptions, code comments

Discovery Workflow

1. ls docs/ (or doc/, documentation/)
   ↓ exists?
   YES → scan structure, build topic map
   NO  → check for standalone doc files (*.md in root)
         ↓ found?
         YES → use available docs
         NO  → suggest creating docs structure
               (see references/doc-patterns.md)

Automated Discovery

Run the scanner script to map available documentation:

python3 scripts/scan_docs.py [project-path]

Output: JSON map of topics → file locations

When Docs Don't Exist

If the codebase lacks documentation:

1. Inform user: "No documentation structure found"
2. Offer to create starter docs: view references/doc-patterns.md
3. Suggest minimal viable structure based on project type

Finding Decisions Without ADRs

If no formal ADRs exist, extract architectural context from:

CHANGELOG.md        → Breaking changes, migration rationale
git log             → Commits w/ "migrate", "refactor", "replace"
PR/MR descriptions  → Discussion threads on major changes
Issue tracker       → Closed RFCs, architecture proposals
Code comments       → // DECISION:, // WHY:, // HACK:

See references/doc-patterns.md → "Fallback: When No ADRs Exist" for git commands & reconstruction templates.

Integration with Research Phase

Use doc-navigator BEFORE grep/glob when:

• Starting work on unfamiliar codebase
• Looking for architectural context
• Understanding feature implementations
• Finding API contracts or schemas

Fall back to grep/glob when:

• Docs don't cover the specific topic
• Need to find implementation details in code
• Searching for specific function/class usage

---

Ref: references/doc-patterns.md for documentation templates when establishing new docs.