research-docs

# Research Docs ## Overview **Your training data is outdated. Current documentation is always more accurate.** When designing features, planning implementation, writing code, or debugging issues involving libraries/frameworks/tools, you MUST fetch current documentation using Context7 before proceeding. ## Core Principle LLM training data becomes stale the moment training ends. Libraries evolve: - APIs change between versions - Best practices get updated - New features get added - Old patterns get deprecated **Never design or implement from memory. Always verify with current docs.** ## Mandatory Workflow ### Step 1: Recognize the Trigger You MUST use documentation search when you encounter ANY of these: - Library name mentioned (react-query, fastapi, pydantic, express, etc.) - Framework name mentioned (Next.js, Django, React, Vue, etc.) - Version number specified (react-query v5, Python 3.12, etc.) - Technical concept tied to specific tool (optimistic updates in react-query) - Implementation questions (how do I X in Y?) - Best practices questions (what's the right way to X?) - Debugging library-specific behavior - Evaluating technology choices for a design - Designing a system that uses external libraries - Any delta phase (design, plan, implement) involving libraries **Red flags that mean you're about to fail:** - "Based on my knowledge of..." - "From what I remember about..." - "The typical pattern for..." - Writing code without checking docs first - Designing around a library without checking current docs - Assuming library capabilities from training data during design - Having uncertainty about the correct approach ### Step 2: Dispatch Documentation Search Subagent **Why subagent instead of direct Context7:** - Saves 10,000-20,000 tokens of context in main agent - Subagent filters docs to only what you need - Main agent stays focused on the task - Better token management across the session **How to dispatch:** Dispatch the `katachi:doc-researcher` agent with the following information: - **Library name**: Exact package/library name (e.g., "react-query", "fastapi", "pydantic") - **Topic**: Specific concept or feature (e.g., "optimistic updates", "path parameters", "field validators") - **What you need**: Specific APIs, patterns, or examples you're looking for The agent will search Context7 documentation and provide a focused synthesis with: - Exact API signatures - Recommended patterns and best practices - Code examples - Version-specific guidance ### Step 3: Act on Verified Patterns **After receiving subagent synthesis:** 1. Cite what you learned: "According to react-query v5 docs (from doc-researcher)..." 2. Use exact API signatures provided 3. Follow recommended patterns from synthesis 4. Note any differences from what you expected 5. If gaps exist, dispatch another search or use WebSearch **During design phases:** - Base design decisions on current library capabilities - Document technology choices with sources from synthesis - Don't propose deprecated patterns as design options - Verify feasibility of design approach with current API **During implementation:** - Use exact API signatures from synthesis - Follow current best practices, not training data patterns - Reference documentation source in code comments when the choice would be unclear **Never:** - Mix training data patterns with doc patterns - Assume API names/signatures - Skip documentation check "to save time" - Design or implement first, verify later - Use Context7 MCP tools directly (always dispatch `katachi:doc-researcher` agent) ## Red Flags - STOP If you're thinking ANY of these, you're about to violate the skill: ### Context Rationalization Flags - "I'm only using X% of budget" - Percentage hides absolute waste - "Well within acceptable limits" - Ignores session-wide compounding - "I have plenty of budget left" - Context is for ENTIRE session - "This is just one search" - "Just one" becomes "just one more" ### Efficiency Framing Flags - "Direct access is more efficient" - You're optimizing for wrong metric - "Subagent dispatch is overhead" - It's an investment, not overhead - "Completed in fewer messages" - Messages don't matter, tokens do - "For straightforward lookups, direct is optimal" - Context math doesn't change ### Quality Justification Flags - "I got comprehensive examples" - You don't need comprehensive, you need relevant - "I can filter the docs myself" - Filtering doesn't remove docs from context - "I need detailed information" - Subagent provides exactly what you need **The context math:** - Direct Context7: 15,000-25,000 tokens per search - Subagent: 2,000-5,000 tokens per search - Difference: 10,000-20,000 tokens SAVED per search - 3 searches: 48,000 tokens saved - That's 48,000 tokens for MORE searches, longer conversations, complex implementations **Never use "I have budget left" to justify waste.** ## When NOT to Use Documentation Search **Skip documentation search for:** - Trivial language built-ins (Python `dict.get`, JavaScript `Array.map`, string methods) - Pure algorithms (sorting, searching, graph traversal) - Questions about YOUR codebase (use Read/Grep) **But DO use documentation search for:** - Third-party libraries, even familiar ones - Framework-specific patterns - Version-specific APIs - Best practices for tools - Complex standard library modules (subprocess, streams, pathlib, logging) - During design phases, when evaluating library fitness - When comparing approaches that involve external libraries - Even if the library was used recently in this session **When in doubt: dispatch a subagent.** The cost of a subagent search (2,000-5,000 tokens) is trivially small. The cost of designing or implementing against stale docs is enormous. ## Context Management Strategy **Why subagents are mandatory:** **Context savings per search:** - Direct Context7: 15,000-25,000 tokens per search - Subagent approach: 2,000-5,000 tokens per search - Savings: 10,000-20,000 tokens per search **Across a session:** - 3 direct searches: ~60,000 tokens - 3 subagent searches: ~12,000 tokens - Savings: ~48,000 tokens **That's 48,000 tokens available for:** - More codebase files - Longer conversations - Additional library searches - Complex implementations ## Verification Checklist Before claiming you've designed or implemented something correctly, verify: - [ ] Dispatched `katachi:doc-researcher` agent to fetch current documentation - [ ] Provided clear library name, topic, and what you need - [ ] Received synthesis with API signatures - [ ] API signatures match documentation exactly - [ ] Patterns follow current best practices from synthesis - [ ] No uncertainties remain about correct approach - [ ] Can cite documentation source for key decisions - [ ] Did NOT use Context7 MCP tools directly **If you have ANY uncertainty after receiving synthesis:** - Dispatch another `katachi:doc-researcher` agent with refined topic - Use WebSearch for supplementary info - Ask human for clarification **Never:** - Use Context7 MCP tools directly - Ship uncertain design or implementation - Skip documentation search to "save time" ## Common Mistakes ### Mistake 1: "I remember this API" ``` ❌ "I know react-query uses useQuery, let me write this..." ✅ "Let me dispatch katachi:doc-researcher to verify the current useQuery API..." ``` **Why it fails:** APIs change. Your memory is from training cutoff. ### Mistake 2: "Subagent overhead isn't worth it" ``` ❌ "This is just one search, I'll use Context7 directly..." ✅ "Even one search saves 15,000 tokens. Always dispatch katachi:doc-researcher." ``` **Why it fails:** "Just one" becomes "just one more" throughout the session. Context compounds. ### Mistake 3: "I'll verify after writing" ``` ❌ [Writes full implementation] "Let me check if this is right..." ✅ [Dispatches katachi:doc-researcher first] "Now I'll implement using verified patterns..." ``` **Why it fails:** Fixing wrong code takes longer than writing correct code once. ### Mistake 4: "This is just a design, I'll check docs during implementation" ``` ❌ [Designs feature assuming library behavior] "I'll verify the APIs when I implement..." ✅ [Dispatches katachi:doc-researcher during design] "Let me verify this is feasible with current APIs..." ``` **Why it fails:** Wrong design foundations compound through the entire feature lifecycle. A design based on deprecated APIs wastes the spec, design, plan, AND implementation phases. ## Summary **Before designing or implementing ANYTHING involving a library/framework:** 1. Recognize trigger (library name → stop) 2. Dispatch `katachi:doc-researcher` agent 3. Provide clear library name, topic, and what you need 4. Receive synthesis with API signatures and patterns 5. Act using verified patterns from synthesis 6. Cite documentation source **Critical rules:** - **NEVER use Context7 MCP tools directly** - **ALWAYS dispatch `katachi:doc-researcher` agent for documentation** - **Context savings: 10,000-20,000 tokens per search** - **Your training data is always outdated** - **Current documentation is always more accurate** - **Dispatch agent first, design or write code second** **This is not optional. This is mandatory.**