---
name: local-research
description: "This skill should be used when performing codebase research with markdown documentation persistence. Triggered by phrases like [local research], [quick research], [load local research], [init local research], [read local research ...]."
---

# Local Research

## Overview

Perform comprehensive codebase research with persistent markdown documentation stored in `~/workspace/llm/research/`. This skill integrates multiple research tools including fast-repo-context skill, knowledge graph queries, and external resources to create structured research documentation.

Use absolute file path in research document for easy share across different projects/repos.

### Automation Script

The skill includes an automation script at `~/.claude/skills/local-research/scripts/research_ops.py` that handles:
- Generating descriptive research names from user queries
- Creating research directories and markdown files with timestamps
- Listing and locating existing research files by keywords
- Providing CLI interface for all research operations

## When to Use This Skill

Use this skill when:
- Need to research and analyze codebase structure and patterns
- Want to create persistent research documentation
- Need to load previous research findings
- User says "local research", "quick research", or "load local research"

## Core Workflow

### Research Generation Process (when user explicitly requests new research)

1. **Generate Research Name**: Create descriptive research name based on user input as `<user-query>`, user input may contain typos, improve it.
2. **Create Research File**: `python3 ~/.claude/skills/local-research/scripts/research_ops.py create "<user-query>"`
3. **Ask Clarifying Questions**: Ask user for more details about research scope
4. **Execute Research Workflow**: Use integrated tools to gather information
5. **Document Findings**: Write results to research markdown file, use absolute file path when writting, do not use `~` path abbreviation.

### Loading Research Process (when user mention load or update doc, or provided doc keywords)

When user requests to "load local research" or similar:
1. **List Research Files**: `python3 ~/.claude/skills/local-research/scripts/research_ops.py list`
2. **Identify Target**: `python3 ~/.claude/skills/local-research/scripts/research_ops.py locate <keywords>`
3. **Load Content**: Read and display the summary of relevant research markdown file

## Research Tools and Methods

### Primary Research Tools

1. **Fast Context Skill** (`fast-repo-context`):
   - load fast-repo-context skill
   - Use for comprehensive codebase understanding
   - Leverages repomix-generated XML for efficient searching

2. **Knowledge Graph** (`kg`):
   - Query related keywords and existing research
   - Use `mcp__kg__query_graph` with semantic search
   - Set `group_id` to organize research by project/topics

3. **External Resources**:
   - **Brightdata**: Use `mcp__brightdata__search_engine` for web research
   - **GitHub**: Use `mcp__github__search_code` or `mcp__github__search_repositories` for external code reference

### Research Execution Order

1. **Initialize Research Environment**:
   ```bash
   python3 ~/.claude/skills/local-research/scripts/research_ops.py create "<user-query>"
   ```

2. **Fast Context Analysis**:
   - Extract code structure, patterns, and key files
   - Document findings in research file

3. **Knowledge Graph Integration**:
   - Query `kg` for related information
   - Use semantic search with research keywords
   - Integrate findings into research documentation

4. **External Research** (if needed):
   - Use Brightdata for web research on related topics
   - Use GitHub tools for external examples and best practices
   - Add external insights to research file

## Research Documentation Structure

Each research markdown file should follow this structure:

```markdown
# <Research Name>

- **Created**: <timestamp>
- **Research Query**: <original user input>

## Executive Summary
<brief overview of findings>

## Codebase Analysis
<findings from fast-repo-context>

## Knowledge Graph Insights
<related information from kg queries>

## External Research
<findings from web/github research if applicable>

## Key Findings
<important discoveries and insights>

## Recommendations
<actionable recommendations based on research>

## Files Referenced
<list of key files analyzed>

## Next Steps
<suggested follow-up actions>
```

- Note: file path in the research doc must use absolute path, do not use `~` abbreviation, because this doc will be shared across different project/repos.

## Loading Research

When user wants to load existing research:

1. **Available Research**: List all research files with timestamps
2. **Search Matching**: Match user keywords to research names/content
3. **Display Findings**: Present the complete research file content

### Script Commands

```bash
# Create new research file
python3 ~/.claude/skills/local-research/scripts/research_ops.py create "<user-query>"

# List all research files (sorted by timestamp)
python3 ~/.claude/skills/local-research/scripts/research_ops.py list

# Locate research file by keywords
python3 ~/.claude/skills/local-research/scripts/research_ops.py locate <keywords...>

# Read specific research file
cat ~/workspace/llm/research/<research-name>-<timestamp>.md
```

## Integration with Other Skills

### Fast Context Integration
- Always invoke `fast-repo-context` skill for codebase analysis
- Follow its mandatory checklist: check repomix freshness, search XML, then optionally KG
- Document steps completed in research file

### Knowledge Graph Integration
- Use consistent `group_id` for related research projects
- Store research summaries in KG for future retrieval
- Query KG before starting new research to avoid duplication

## Research Naming Conventions

Generate descriptive research names:
- Convert user input to kebab-case
- Include domain/technology focus
- Example inputs to names:
  - "analyze authentication system" → "authentication-system-analysis"
  - "react performance issues" → "react-performance-investigation"
  - "api design patterns" → "api-design-patterns-research"

## Error Handling

- If research directory creation fails, check permissions and path
- If fast-repo-context claude skill is unavailable, fall back to direct code search
- If external resources are unreachable, continue with internal research
- Always document any limitations or issues encountered

# Example

<example>
<user>
please load local research on "authentication system analysis" and update the document with any new findings.
</user>

<assistant>
```bash
python3 ~/.claude/skills/local-research/scripts/research_ops.py locate authentication system analysis
```
Good, found the research file at `<file-path>`. Now loading the content and summarizing the key points for you.
</assistant>
</example>