---
name: docs-use
description: |
  TRIGGER: Auto-activate when user asks to write, implement, build, fix, debug,
  modify, refactor, or create code that involves project libraries.
  Also activate on "how do I use", "what's the API for", "show me how to".
  DO NOT TRIGGER: on /docs-setup commands, non-coding questions, general chat,
  git operations, or file reading without implementation intent.
  Enforces documentation lookup priority: local pre-fetched docs first,
  then context7 and web search (equal secondary sources).
allowed-tools:
  - Read
  - Glob
  - Grep
  - mcp__context7__resolve-library-id
  - mcp__context7__query-docs
  - WebSearch
  - WebFetch
---

# docs-use

Enforce documentation lookup priority when working on coding tasks.

## Session Verification (Once Per Session)

At the start of a coding task, read `docs/official-docs/state.json` in the project root.

### If state.json is missing:
- Print a brief one-liner: "No pre-fetched docs found. Run `/docs-setup init` to set up local documentation."
- Only suggest once per session (rely on conversation memory)
- Proceed with the coding task without blocking

### If state.json is found:
Check `status` and `fetchedAt` fields from state.json only. Do NOT read project dependency files — that's docs-setup's job.

1. **Freshness**: If any library's `fetchedAt` is older than 30 days, suggest: "Some local docs are stale. Run `/docs-setup update` to refresh."
2. **Status**: If any library has `status: "version-mismatch"` or `"error"`, briefly report it

Report issues once as a brief warning. Never block the task.

## Documentation Priority Chain

No token or page count limits — read what's needed for the task.

### 1. Local docs first (highest priority)

When a library is involved in the task:
1. Check state.json for the library
2. Use `sections` from state.json to understand directory grouping and target the most relevant section
3. Use Grep across `docs/official-docs/{lib}/` (or a specific section subdirectory) for relevant terms
4. Read the most relevant pages found by Grep

### 2. context7 and WebSearch/WebFetch (equal, secondary)

Use when:
- Local docs don't cover the topic
- Library isn't pre-fetched in state.json
- Need the very latest information not in local docs

Use whichever source is more appropriate:
- **context7** for general library documentation and API reference
- **WebSearch/WebFetch** for specific, latest, or niche information

Both are equal fallbacks — choose based on what fits the query.

## Missing Library Suggestion

When encountering a library NOT in state.json:
- Suggest `/docs-setup add <lib-name>` the first time it's encountered in the session
- Then fall through to context7/WebSearch silently
- Do not repeat the suggestion for the same library in the same session

## Library Detection from Task

Detect which libraries are relevant through:
- Explicit mention in the user's prompt
- Import analysis of files being edited
- Project framework context from state.json

## Constraints

- **Read-only**: Never modify docs files or state.json
- **Never auto-invoke** /docs-setup
- **Never block** the coding task for doc staleness or missing docs
- **Use Grep** to find the right pages — do not sequentially read all docs
- **Transparent operation**: Don't announce the priority chain. Just read docs and use them naturally. Only mention the source if asked.