dev-docs-fetch（开发文档获取）

dev-docs-fetch

Fetch and cache library documentation via Context7 MCP.

Context Files

• $JAAN_CONTEXT_DIR/tech.md — Tech stack for library auto-detection

- Uses sections: #current-stack, #frameworks

• $JAAN_LEARN_DIR/jaan-to-dev-docs-fetch.learn.md — Past lessons (loaded in Pre-Execution)
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md — Language resolution protocol

Input

Arguments: $ARGUMENTS

• [library-names...] — Explicit library names (e.g., fastapi react nextjs)
• No arguments — Auto-detect from $JAAN_CONTEXT_DIR/tech.md

If no input and no tech.md, ask: "Which libraries do you need documentation for?"

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: dev-docs-fetch Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Also read context files if available:

• $JAAN_CONTEXT_DIR/tech.md — Know the tech stack for library detection

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_dev-docs-fetch

Language exception: Library names, Context7 IDs, package names, and cache file paths are NOT affected by this setting — always English.

Token Budget & Efficiency Rules

Target: <10,000 tokens per execution

• Use Bash to check cache freshness before MCP calls (no file reads for fresh cache)
• Fetch only libraries relevant to current task
• Cache aggressively (7-day TTL)
• Max 3-5 libraries per run
• Report concisely (no verbose logging)

PHASE 1: Analysis (Read-Only)

Step 1: Parse Arguments & Detect Libraries

If $ARGUMENTS provided: Extract library names directly:

• Example: /jaan-to:dev-docs-fetch fastapi openai → ["fastapi", "openai"]
• Example: /jaan-to:dev-docs-fetch react → ["react"]

If no arguments (auto-detection):

1. Read $JAAN_CONTEXT_DIR/tech.md #current-stack section
2. Extract framework and library names from the tech stack
3. Map to Context7-searchable names (use the framework/library name as-is)
4. If tech.md missing → ask user for library names

No hardcoded library tiers. This skill is tech-agnostic — it reads whatever stack is declared in tech.md and resolves via Context7's search.

Step 2: Cache Freshness Check

For each library to check, determine cache status:

Cache path: $JAAN_OUTPUTS_DIR/dev/docs/context7/{library-name}.md

CACHE_DIR="$JAAN_OUTPUTS_DIR/dev/docs/context7"
mkdir -p "$CACHE_DIR"

For each library (e.g., fastapi):

CACHE_FILE="$CACHE_DIR/fastapi.md"

if [ -f "$CACHE_FILE" ]; then
    FRESH=$(find "$CACHE_FILE" -mtime -7 -print 2>/dev/null)
    if [ -n "$FRESH" ]; then
        echo "FRESH"
    else
        if [ "$(uname)" = "Darwin" ]; then
            MTIME=$(stat -f %m "$CACHE_FILE")
        else
            MTIME=$(stat -c %Y "$CACHE_FILE")
        fi
        NOW=$(date +%s)
        DAYS=$(( ($NOW - $MTIME) / 86400 ))
        echo "STALE ($DAYS days)"
    fi
else
    echo "MISSING"
fi

Build lists:

• FRESH: Libraries with cache <7 days old — skip fetch
• STALE: Libraries with cache ≥7 days old — re-fetch
• MISSING: Libraries without cache — fetch

Present summary:

Cache Status:
✓ Fresh (N): lib1, lib2 (will skip)
↻ Stale (N): lib3 (X days old)
⬇ Missing (N): lib4, lib5

Will fetch: N libraries (stale + missing)

HARD STOP — Confirm Fetch Plan

Use AskUserQuestion:

• Question: "Fetch {N} libraries? ({fetch-list})"
• Header: "Fetch"
• Options:

- "Proceed" — Fetch listed libraries - "Edit list" — Modify which libraries to fetch - "Cancel" — Skip fetching

Do NOT proceed to Phase 2 without explicit approval.

PHASE 2: Fetch & Store

Step 3: Resolve Library IDs

For each library in the fetch list:

Use mcp__context7__resolve-library-id:

Input:
  libraryName: "{name}"

Expected Output:
  Context7-compatible library ID (e.g., /tiangolo/fastapi)

Error handling — Library not found:

⚠️ Library "{name}" not found in Context7

Options:
  retry <name> — Try different library name
  skip — Continue without this library

Wait for user input before proceeding.

Step 4: Fetch Documentation

For each resolved library:

Use mcp__context7__get-library-docs:

Input:
  context7CompatibleLibraryID: "{resolved-id}"
  mode: "code"
  topic: (optional, extracted from task context)

Mode selection:

• Default: mode="code" (API references + code examples)
• Use mode="info" if task mentions: architecture, concepts, design patterns, how it works

Topic extraction (optional): Extract specific topic from task description if mentioned:

• "FastAPI middleware" → topic="middleware"
• "React hooks" → topic="hooks" If no specific topic, omit the topic parameter.

Error handling — API failure:

❌ Context7 API error for "{name}"

Fallback Strategy:
  Stale cache available: {name}.md ({age} days old)
  Use stale cache? (better than nothing)

Options:
  use-stale — Use stale cache
  skip — Continue without this library
  retry — Try again

Error handling — Network timeout: Retry up to 3 times. After 3 failures, offer skip or use-stale.

Step 5: Store Documentation

For each successfully fetched library:

File path: $JAAN_OUTPUTS_DIR/dev/docs/context7/{library-name}.md

Naming convention: Lowercase, hyphenated, match package name. Examples: fastapi.md, python-telegram-bot.md, nextjs.md

Handle created date:

• If file exists (re-fetch): read existing frontmatter, preserve created date, update updated
• If new file: set both created and updated to today

Write file with YAML frontmatter:

---
title: {Library Name} Documentation
library_id: {context7-compatible-library-id}
type: context7-reference
created: {YYYY-MM-DD}
updated: {YYYY-MM-DD}
context7_mode: {code|info}
topic: {topic_if_specified|null}
tags: [context7, {library-name}, technical-reference]
source: Context7 MCP
cache_ttl: 7 days
---

{Full Context7 markdown response}

Verify each write:

ls -lh "$JAAN_OUTPUTS_DIR/dev/docs/context7/{library-name}.md"

Step 6: Summary Report

Documentation Fetch Complete

Fetched (N):
  ✅ lib1.md (code mode, XX KB)
  ✅ lib2.md (info mode, topic: hooks, XX KB)

Cached - Fresh (N):
  ✓ lib3.md (X days old)

Skipped (N):
  ⚠️ lib4 (not found in Context7)

Storage: $JAAN_OUTPUTS_DIR/dev/docs/context7/
Total libraries available: N

Next step: Documentation ready for use in planning and implementation phases.

Step 7: Suggest Next Actions

Context-aware recommendations:

• Docs fetched for backend libraries → suggest /jaan-to:backend-scaffold or /jaan-to:dev-tech-plan
• Docs fetched for frontend libraries → suggest /jaan-to:frontend-scaffold
• Docs fetched for testing libraries → suggest /jaan-to:qa-test-generate
• General → "Documentation ready for use in planning and implementation phases."

Step 8: Capture Feedback

Use AskUserQuestion:

• Question: "How did the documentation fetch turn out?"
• Header: "Feedback"
• Options:

- "Perfect!" — Done - "Missing library" — What library should we try to find? - "Learn from this" — Capture a lesson for future runs

If "Learn from this": Run /jaan-to:learn-add dev-docs-fetch "{feedback}"

Scope Boundaries

• Does NOT generate code (only fetches and caches reference documentation)
• Does NOT modify project source files
• Does NOT start services or run builds
• Only writes to $JAAN_OUTPUTS_DIR/dev/docs/context7/
• Requires Context7 MCP server configured (.mcp.json for Claude Code, ~/.codex/config.toml for Codex)

DAG Position

(standalone — callable from any skill's Phase 1)
  |
  v
dev-docs-fetch
  |
  v
dev-tech-plan, backend-scaffold, frontend-scaffold, etc.

Skill Alignment

• Two-phase workflow with HARD STOP for human approval
• Tech-agnostic via tech.md detection (no hardcoded library lists)
• Uses $JAAN_* environment variables throughout
• Learning integration via $JAAN_LEARN_DIR

Definition of Done

• Cache checked before any fetch (7-day TTL enforced)
• Libraries fetched via Context7 MCP with YAML frontmatter
• Error handling covers: not found, API failure, timeout
• Summary report shown to user
• User feedback captured