Conduct

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

• 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]"
  • Example formats:
    • With URL: 1. [Microsoft Learn - Azure Functions Overview](https://docs.microsoft.com/en-us/azure/azure-functions/)
    • MCP with source: 2. [Stack Overflow - Case Management Best Practices](https://stackoverflow.com/questions/12345) - Retrieved via Perplexity
    • MCP without URL: 3. [Analysis: Case Management Systems Comparison] - No direct URL - via Perplexity Reason (Query: "compare case management systems")

• Cite all MCP server(s) used, and any Tool calls (if MCP had issues) whenever possible

• Do NOT include the thinking mode in the file name

• Document Structure Requirements:

  • Every research document MUST follow this exact structure:
  • Header metadata section (at the very top)
  • Main content sections
  • Footer metadata section (at the very bottom)

• Header Metadata Format (place at the TOP of every document):

  ---
  title: [Research Topic Title]
  date_created: [Use ISO_TIMESTAMP_FORMAT]
  author: Claude (Anthropic)
  model: [model name used]
  thinking_mode: [mode used or "standard"]
  research_type: [tools/technologies | companies/organizations | concepts/methodologies]
  tags: [comma-separated relevant tags]
  status: final
  version: 1.0
  ---
  
  # [Main Title of Research Document]
  
  ## Executive Summary
  [Brief 2-3 paragraph summary of the research findings]
  

• Query Documentation:

  • Include a "## Research Queries" section BEFORE the References section
  • Document all search queries used, organized by MCP server
  • Format: ### [MCP Server Name] followed by numbered list of queries
  • Include any failed queries with error notes
  • This helps with reproducibility and troubleshooting

• References Section CRITICAL Requirements:

  • EVERY reference MUST have a clickable URL or clearly indicate no URL is available
  • Correct formats:
    • Direct URL: 1. [Title](https://example.com)
    • With MCP note: 2. [Title](https://example.com) - via Perplexity
    • No URL available: 3. [Title] - No URL available - via Perplexity (query: "search terms")
  • NEVER use these incorrect formats:
    • ❌ [Title](Retrieved via mcp__perplexity__search) - NOT a valid URL
    • ❌ [Title](Retrieved via WebSearch) - NOT a valid URL
    • ❌ Any reference without an actual http/https URL in parentheses
  • Track URLs during research: As you research, maintain a list of all actual URLs discovered to use in references

• Footer Metadata Format (place at the BOTTOM of every document after References):

  ---
  
  ## Document Metadata
  
  ### Generation Details
  - **Generated by**: Claude (Anthropic)
  - **Model Version**: [specific model used]
  - **Generation Date**: [Use ISO_TIMESTAMP_FORMAT]
  - **Total Research Time**: [time in minutes/seconds]
  - **Word Count**: [approximate word count]
  
  ### Research Methodology
  - **Primary Sources**: [count] sources
  - **MCP Servers Used**: [list of successful servers]
  - **Search Queries**: [total count] queries executed
  - **Content Synthesis**: Direct synthesis (no parallel agents)
  
  ### Quality Metrics
  - **Source Verification**: Cross-referenced across multiple sources
  - **Currency**: Information current as of [date]
  - **Comprehensiveness**: [Basic | Standard | Comprehensive | Exhaustive]
  - **Confidence Level**: [Low | Medium | High] based on source quality
  
  ### Document Control
  - **Version**: 1.0
  - **Status**: Final
  - **License**: For internal use only
  - **Last Modified**: [Use ISO_TIMESTAMP_FORMAT]
  
  ### Inaccessible Sources
  *The following URLs were identified during research but could not be accessed programmatically:*
  - [List any Reddit URLs that were found but blocked]
  - [List any forum URLs that returned 403/blocked errors]
  - [List any other URLs that failed to fetch with reason]
  - *Note: These links may be accessible via manual browser access*
  
  ---
  *This document was automatically generated by Claude using the research command workflow.*
  

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
   • Do NOT continue without asking the user if it should continue
   • When in doubt STOP and do NOT proceed if there are MCP errors, report any issues

5. Clarify Ambiguity

   • If at any time you discover that the RESEARCH_TOPIC_PROMPT is not specific enough, or ambiguous - STOP and ask the user to clarify
   • For example, say the research topic is "windows repair", do they mean the operating system or glass window repair?
   • For person searches with common names:
     • If initial searches reveal multiple people with the same name
     • Ask for clarifying details (employer, location, profession, timeframe)
     • Example: "I found multiple Kyle Sextons - one is a chamber consultant/author, another is a musician. Which one should I research?"
   • If this happens and the user submits a new prompt that makes any research irrelevant, clear all research done up to this point and start over

6. MANDATORY PARALLEL EXECUTION VALIDATION

   • BEFORE beginning any research: Validate that you will use parallel tool execution
   • REQUIREMENT: ALL MCP tool calls MUST be executed in parallel in a single message
   • VALIDATION CHECKPOINT: Ask yourself "Am I about to send multiple individual tool calls?"
   • IF YES: STOP and restructure to send all tool calls in one message block
   • PERFORMANCE TARGET: 60-80% performance improvement through parallel execution
   • NO EXCEPTIONS: Sequential tool execution is prohibited for research workflows

7. Execute Research

   • Utilize the PRIMARY_MCP_SERVERS to do all the external research
   • CRITICAL: Execute ALL MCP tool calls in parallel by sending them in a single message with multiple tool use blocks
   • Do NOT execute MCP calls sequentially - batch them together for parallel execution
   • When making multiple search/research calls, send them all at once to maximize efficiency
   • ENFORCEMENT: If you find yourself making sequential calls, STOP and batch them into parallel execution
   • Example: Send perplexity search, firecrawl search, and ref search all in the same message
   • URL Tracking Requirements During Research:
     • CRITICAL: As you execute each search/scrape, maintain a list of ALL URLs discovered
     • For WebSearch: Record every URL returned in the search results
     • For Firecrawl: Record the exact URL that was scraped
     • For Perplexity: Extract and record any source URLs mentioned in the response
     • For Context7/Ref: Record the documentation URL if provided
     • Store these URLs with their titles for use in the References section
   • Track Inaccessible Sources:
     • When WebSearch finds Reddit/forum links but can't access content, add to INACCESSIBLE_SOURCES list
     • When Firecrawl or WebFetch returns 403/blocked errors, add URL and error to list
     • Include the reason for inaccessibility (e.g., "Reddit blocks automated access", "403 Forbidden")
     • These will be reported to user for potential manual review

8. Synthesize Findings

   • Once all research is complete, synthesize the findings directly without using parallel Task agents
   • CRITICAL Identity Verification Step:
     • Before synthesis, review all collected information for identity conflicts
     • If researching a person and finding multiple distinct careers/roles:
       • Check if timeframes overlap impossibly
       • Look for geographic inconsistencies
       • Verify if specialties are realistically combinable
       • When in doubt, present as potentially different people
   • Create a comprehensive report covering all aspects of the research topic
   • Structure the content with the REQUIRED format:
     1. Header metadata (YAML frontmatter)
     2. Executive Summary
     3. Main content sections
     4. Disambiguation Notes (if needed for people/entities)
     5. Research Queries section
     6. References section
     7. Footer metadata section
   • Ensure all content flows naturally and maintains consistency
   • Do NOT create temporary files or use Task agents for synthesis
   • CRITICAL: Use ONLY valid markdown syntax in the final document:
     • Use - or * for bullet points (NEVER use • or other Unicode bullets)
     • Use 1., 2., 3. for numbered lists
     • Use #, ##, ### for headers with proper spacing
     • Ensure blank lines between sections, lists, and code blocks

9. Save Documentation

   • Create the markdown file in the RESEARCH_OUTPUT_DIRECTORY
   • Follow the FILENAME_FORMAT structure which includes the inline timestamp command
   • The inline timestamp command will automatically generate the correct UTC timestamp
   • IMPORTANT: Create ONLY ONE research file per command execution
   • All research findings MUST be consolidated into a single comprehensive document
   • Do NOT create multiple files for different sections or aspects of the research
   • Do NOT create supporting or auxiliary files
   • The single file should contain ALL research content, references, and metadata
   • Record FILE_GENERATION_END = [timestamp when file is saved]

10. Update INDEX.md

• 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.