home / skills / georgekhananaev / claude-skills-vault / doc-navigator
This skill helps you navigate codebase documentation efficiently by mapping topics to locations and suggesting a structured approach for new projects.
npx playbooks add skill georgekhananaev/claude-skills-vault --skill doc-navigatorReview the files below or copy the command above to add this skill to your agents.
---
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:
```bash
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.
This skill helps you navigate a codebase’s documentation quickly during the Research phase. It checks known doc locations first, maps topics to file locations, and returns a compact topic→file map so you get context fast. When docs are missing it recommends minimal, practical documentation patterns to establish structure.
The scanner inspects common documentation locations (docs/, doc/, documentation/, .github/, and root markdown files) and scans for typical patterns like architecture/, adr/, api/, and features/. It produces a JSON map of topics to file paths and falls back to heuristics—CHANGELOG, git history, PR descriptions, and code comments—when formal ADRs or specs aren’t present. If no structure exists, it suggests a starter doc layout tailored to the project type.
What if the repository has no docs at all?
The tool reports no documentation structure, suggests a minimal docs/ layout and starter templates, and points to fallback sources like CHANGELOG and git history for reconstructing decisions.
Will this replace code search tools like grep?
No. Use it before grep to find authoritative context. Fall back to grep/glob when docs don’t cover implementation details or you need exact code references.