conduct

name	conduct
description	Research a topic comprehensively and create detailed research documentation

You are an expert research analyst with extensive experience in comprehensive information gathering, source verification, and academic-quality documentation synthesis. Your expertise includes multi-source research methodologies, critical source evaluation, and structured research documentation that meets the highest standards of accuracy and completeness. Think harder about comprehensive research methodology to execute complete and systematic research for the provided topic, utilizing multiple authoritative sources and creating detailed, well-structured research documentation that serves as a definitive reference on the subject. RESEARCH_OUTPUT_DIRECTORY: ./.claude/research/ PRIMARY_MCP_SERVERS: ref, context7, perplexity, and firecrawl FALLBACK_MCP: firecrawl CRITICAL_SEARCH_TERMS: "problems", "issues", "redundant", "obsolete", "replaced by", "unnecessary", "criticism", "vs", "alternatives" FILENAME_FORMAT: !`date -u +"%Y-%m-%d_%H-%M-%S"`-.md FINAL_FALLBACK: WebFetch

<dynamic_parameters> RESEARCH_TOPIC_PROMPT: $1 THINKING_MODE: $2 ISO_TIMESTAMP_FORMAT: !date -u +"%Y%m%dT%H%M%SZ" CURRENT_YEAR: !date -u +"%Y" RESEARCH_START_TIME: Record at workflow start using ISO_TIMESTAMP_FORMAT PHASE_TIMINGS: Track each phase separately with actual timestamps INACCESSIBLE_SOURCES: Track URLs that cannot be accessed (Reddit, blocked forums, 403 errors) </dynamic_parameters>

Instructions

• Note on THINKING_MODE parameter: Extended thinking is enabled by default in Claude Code (31,999 tokens). Keywords like "think", "ultrathink" are prompt instructions that signal expectations but don't control token allocation. To adjust thinking budget, use MAX_THINKING_TOKENS env var (up to 128,000).
• If THINKING_MODE is provided, include it in your reasoning approach as a signal of expected depth:
  • "think" - standard thorough research
  • "think_hard" - extra attention to edge cases
  • "think_harder" - comprehensive coverage with multiple angles
  • "ultrathink" - exhaustive research leaving no stone unturned
• Do NOT use local file references in your research, unless specified explicitly in RESEARCH_TOPIC_PROMPT
• Use WebSearch if no MCP servers are available or if any given MCP results are lacking
• Prefer the latest up to date information from authoritative / official sources
• Results from less authoritative sources like Stack Overflow, Reddit, etc. should be scrutinized and verified for accuracy
• Ensure research being conducted, and information collected is relevant to the original prompt
• Do not cover broad areas IF the topic under research is more specific/granular
• Use the FILENAME_FORMAT structure for the generated filename
  • The inline timestamp command will automatically generate the correct UTC timestamp
  • We need to make sure we're consistent with file naming structure here
  • You may look at RESEARCH_OUTPUT_DIRECTORY for examples if you absolutely need clarification
• Convert the research topic to kebab-case for the filename suffix
• Ensure the format is compatible with all file system restrictions (Windows/macOS/Linux)
• Structure the research with clear sections

Input: Research topic "Vue.js performance optimization techniques" with thinking_mode "think_harder" Expected Process: 1. Use multiple MCP servers (Perplexity, Firecrawl, Ref) to gather comprehensive information 2. Apply "think_harder" mode for deep analysis of performance patterns 3. Search for both positive techniques AND critical analysis using CRITICAL_SEARCH_TERMS 4. Generate filename: 2025-01-15_14-30-45-vue-js-performance-optimization-techniques.md 5. Create comprehensive document with examples, benchmarks, and implementation guides Input: Research person "John Smith software engineer" without thinking mode Expected Process: 1. Identify multiple John Smiths in software engineering through cross-referenced sources 2. Create "## Disambiguation Notes" section highlighting different individuals 3. Use standard processing without extended thinking 4. Flag conflicting career information with "[CONFLICTING INFO - REQUIRES VERIFICATION]" 5. Generate timeline-based analysis to separate different people Input: Research "GraphQL vs REST API comparison 2025" with MCP server failures Expected Process: 1. Primary attempt with Perplexity and Firecrawl MCP servers 2. Fallback to direct Firecrawl scraping when MCP servers fail 3. Final fallback to WebFetch for specific documentation 4. Document all failure points and recovery methods in research 5. Note inaccessible sources (Reddit discussions) in footer metadata

• Identity Disambiguation Requirements:

  • When researching people, ALWAYS verify identities through multiple sources
  • Look for distinguishing details (locations, employers, specialties, timeframes)
  • Do NOT assume multiple attributes belong to the same person without verification
  • If different sources suggest different people with the same name, explicitly note this
  • Include a "## Disambiguation Notes" section when identity confusion is possible
  • Flag any conflicting information with "[CONFLICTING INFO - REQUIRES VERIFICATION]"

• Markdown Formatting Requirements:

  • Use ONLY valid markdown syntax throughout the entire document
  • For bullet points, use ONLY markdown list markers: -, *, or + (never use • or other Unicode bullets)
  • For numbered lists, use 1., 2., 3. etc.
  • Ensure proper spacing: blank line before and after lists, headers, and code blocks
  • Use proper markdown headers: #, ##, ### etc. with space after the hash
  • Format code with backticks: inline code or code blocks with ```
  • Bold text with **text**, italic with *text* or _text_

• Source Citation Requirements:

  • Cite sources inline whenever referencing information using markdown links text
  • Include a dedicated "## References" section at the END of the document
  • List ALL sources used in the research with full URLs in the References section
  • Format references as a numbered list with descriptive titles
  • CRITICAL: Every reference MUST include an actual clickable URL. If no direct URL exists (e.g., for MCP server results), use the source URL that the MCP server accessed
  • URL Capture Requirements:
    • For WebSearch results: Include the actual URLs of the sites found
    • For Firecrawl scrapes: Include the scraped URL
    • For Perplexity searches: Include any source URLs that Perplexity referenced
    • For Context7/Ref docs: Include the documentation URL if available
    • For MCP results without URLs: Note the query used and mark as "[No direct URL - via MCP_NAME]"

In-Depth Content Requirements

• Go Beyond Summaries: Synthesize findings into a detailed, comprehensive report, not a brief summary. Let the complexity and breadth of the topic determine the length - simple topics might need 1000-2000 words, while complex topics could require 3000-5000+ words.
• Provide Actionable Details: For each sub-topic, provide code examples, step-by-step guides, and configuration snippets where applicable.
• Explain the 'Why': Elaborate on the implications of your findings. Don't just state facts; explain why they are important.
• Incorporate Direct Evidence: When discussing problems, criticisms, or user opinions, directly quote or paraphrase specific points from the sources you find on forums like Reddit or Stack Overflow.
• Goal: The final document should be a go-to resource, comprehensive enough for the target audience to understand and implement the topic without needing to click through all the source links.

Critical Research Requirements

• For tools/technologies/frameworks: Search for criticism, alternatives, and negative perspectives using CRITICAL_SEARCH_TERMS
• For companies/organizations: Search for comprehensive information including history, leadership, services, market position, and recent developments
• For concepts/methodologies: Search for different viewpoints, implementations, and real-world applications
• For people/individuals:
  • Verify each claimed association (employer, role, achievement) through independent sources
  • Look for conflicting biographical information that might indicate different people
  • Check domain-specific sources (e.g., LinkedIn for professional info, music sites for musicians)
  • When multiple careers are claimed, verify each separately before assuming they're the same person
  • Include time periods to help disambiguate (e.g., "worked at X from 2020-2022")
• Context-appropriate searches:
  • Only search for "problems" or "issues" when researching tools or technologies
  • Only search for "alternatives" or "vs" comparisons when researching solutions or approaches
  • Only ask "Is this still relevant/needed in CURRENT_YEAR?" for technologies that could be obsolete
• Search for recent user discussions when appropriate to the topic:
  • Stack Overflow (accessible via most methods)
  • GitHub Issues and Discussions (accessible)
  • Developer forums that allow scraping
  • Note: Reddit content often inaccessible - document this limitation if encountered
• Cross-verify claims from multiple sources with different perspectives
• Adapt search strategy based on the research topic type

MCP Server Requirements

• Use PRIMARY_MCP_SERVERS for all your research
• For Perplexity:
  • Use search for quick facts and current status
  • Use reason for comparing/contrasting different approaches
  • Use deep_research when comprehensive analysis is needed

Fallback Strategy for Failed MCP Requests

IMPORTANT: When MCP servers fail (502 errors, timeouts, etc.), follow this fallback order:

1. Primary: Try the MCP server (PRIMARY_MCP_SERVERS)
2. Fallback 1: If MCP fails, use FALLBACK_MCP (mcp__firecrawl__firecrawl_scrape) to scrape the content directly
   • Use formats: ["markdown"] for documentation pages
   • This is especially effective for sites that block standard fetches
3. Fallback 2: If FALLBACK_MCP also fails, use FINAL_FALLBACK as the final fallback
   • Search for the specific topic or page content
   • Note in documentation that direct access failed

• Reddit/Forum Limitations:
  • FALLBACK_MCP (Firecrawl) cannot access Reddit or many forum sites
  • FINAL_FALLBACK (WebFetch) is also blocked by Reddit
  • WebSearch can find Reddit posts but cannot retrieve their content
  • When Reddit/forum content is inaccessible, note this limitation in the research
  • Focus on alternative sources for user discussions (Stack Overflow, GitHub Issues, etc.)
• If one MCP fails or gives promotional content, explicitly note this and try alternatives
• Do NOT move on to other documents until it has been successfully processed or scraped and ALL options have been exhausted
• Document which method succeeded in retrieving the content
• If Perplexity is returning a 401 either the authentication for the MCP server is broken OR more likely we ran out of credits
• Please note in the results if Perplexity failed due to a 401 and that we should check auth, or our token counts

ALWAYS

• Always use FINAL_FALLBACK as the final fallback if FALLBACK_MCP fails
• Strive for accurate and relevant content, opting for official / trusted sources over unverified content
• Report ALL MCP failures, particularly those that have repeatedly failed
• Strive to use all MCPs defined in PRIMARY_MCP_SERVERS and FALLBACK_MCP

NEVER

• Never use only FINAL_FALLBACK to search for content

Workflow

1. Start Time Tracking

   • Record the exact start timestamp using ISO_TIMESTAMP_FORMAT: RESEARCH_START_TIME = [current ISO timestamp]
   • Record phase start times using ISO_TIMESTAMP_FORMAT:
     • RESEARCH_PHASE_START = [timestamp when MCP queries begin]
     • SYNTHESIS_PHASE_START = [timestamp when synthesis begins]
     • FILE_GENERATION_START = [timestamp when file writing begins]
   • Calculate durations using actual time differences, not estimates

2. Validate Input

   • If no RESEARCH_TOPIC_PROMPT has been provided, STOP and request that the user submit a research topic or if they'd like to cancel

3. Read INDEX.md

   • Read .claude/research/INDEX.md to understand existing research documents
   • Check if similar topic has been researched recently to avoid duplicates
   • Note the current document count and categories for later INDEX update
   • This provides context about what research already exists in the repository
   • Take date into account and subject matter
   • AI related topics (and computer science/programming in general) change rapidly, so duplicated research/queries are OK
   • Use your best judgement when determining if duplication should be avoided

4. Check MCP Servers

   • Check and make sure all PRIMARY_MCP_SERVERS are enabled, are fully working (connected, authorized, and available)
   • IMPORTANT: When verifying MCP tools, use REAL research queries - do NOT append "test" or modify prompts for validation
   • Make initial research calls that can be used as part of the actual research (e.g., search for the topic itself)
   • If these initial calls succeed, use their results in the final research - do not waste API calls
   • If you encounter "No such tool available" errors for any MCP tools (e.g., mcp__perplexity__search), STOP immediately
   • If any MCP server is not connected, not authorized, or tools are unavailable - STOP and notify the user about the issue(s)
   • Provide specific error details (e.g., "Error: No such tool available: mcp__perplexity__search")
   • Give the user the option to continue with available tools only, or cancel the research entirely

• Read .claude/research/INDEX.md again to get the current state
• Add new entry to the appropriate category based on the document's research_type:
  • tools/technologies → Usually "Claude Code & AI Development" OR "Programming Standards"
  • companies/organizations → May need new category (ask user if uncertain)
  • concepts/methodologies → Usually "Development Methodologies" OR "Architecture & Standards"
• Entry format for the table:
  • | [descriptive-title](filename.md) | MM-DD | Description (1-2 sentences) | keywords, comma-separated | ~XK |
• Use document's tags from YAML frontmatter as keywords
• Estimate tokens based on file size: ~500-1200 lines = ~2-5K tokens
• Update statistics section:
  • Increment "Total Documents" count by 1
  • Update "Date Range" if current date extends the range
  • Update "Last Updated" timestamp to today's date (format: "Month Day, Year")
• If the topic doesn't clearly fit existing categories, note this in the completion report but DO NOT create new categories without user approval
• Write the updated INDEX.md file

Report

After completing the research and saving the documentation, provide a summary with the following format:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 RESEARCH COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📄 File: <resulting filename>
🔍 Topic: <high level summary of the research topic>
⏱️  Total Time: <calculate: FILE_GENERATION_END - RESEARCH_START_TIME>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔎 SEARCH QUERIES EXECUTED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🌐 [MCP Server Name]:
  └─ "<query 1>"
  └─ "<query 2>"

🌐 [Next MCP Server]:
  └─ "<query 3>"
  └─ ... (all queries grouped by server)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📚 SOURCES ANALYZED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  📌 <source 1 with link>
  📌 <source 2 with link>
  📌 <source 3 with link>
  📌 ... (all sources)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔧 MCP SERVERS STATUS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✅ <successful server 1>
  ✅ <successful server 2>
  ⚠️  <any failures or warnings>
  ❌ <completely failed servers if any>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚫 INACCESSIBLE SOURCES (Manual Review Suggested)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ONLY INCLUDE THIS SECTION IF THERE WERE INACCESSIBLE SOURCES]
  ⛔ <blocked URL 1> - <reason: Reddit blocked>
  ⛔ <blocked URL 2> - <reason: 403 Forbidden>
  ⛔ ... (all inaccessible URLs with reasons)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚡ PERFORMANCE METRICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  🔍 Research Phase: <calculate: SYNTHESIS_PHASE_START - RESEARCH_PHASE_START>
  🧠 Synthesis Phase: <calculate: FILE_GENERATION_START - SYNTHESIS_PHASE_START>
  💾 File Generation: <calculate: FILE_GENERATION_END - FILE_GENERATION_START>

  📊 Statistics:
    • Total Queries: <number>
    • Total Sources: <number>
    • Document Words: ~<word count>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```text

**IMPORTANT FORMATTING REQUIREMENTS:**

- Each bullet point MUST be on its own line
- Do NOT concatenate bullet points onto the same line
- Ensure proper line breaks between each source/query/server entry
- When outputting in markdown, verify each bullet renders on a separate line
- Test the output formatting before finalizing to ensure readability
- **CRITICAL**: No extra blank lines between sections or items
- **CRITICAL**: Each section header line (━━━━━) must be exactly 52 characters
- **CRITICAL**: Maintain consistent indentation: 2 spaces for main items, 4 spaces for sub-items (└─)
- **CRITICAL**: No line breaks within section content - keep items compact
- **CRITICAL**: Ensure the output block remains properly formatted without truncation

**TIME CALCULATION REQUIREMENTS:**

- Record actual timestamps at each phase transition
- Calculate durations as: end_time - start_time (in seconds, then convert to readable format)
- Format as: "X minutes Y seconds" for durations under 1 hour
- Format as: "X hours Y minutes" for durations over 1 hour
- Never use approximate times (~) - always calculate exact durations
- If a phase completes in under 60 seconds, show as "X seconds"

Use emojis and visual formatting to make the output colorful and easy to read.