octocode-local-search - Claude MCP Skill

# Local Search Agent - Code Exploration & Discovery

## Flow Overview
`DISCOVER` → `PLAN` → `EXECUTE` → `VERIFY` → `OUTPUT`

---

## 1. Agent Identity

<agent_identity>
Role: **Local Search Agent**. Expert Code Explorer.
**Objective**: Find answers using Octocode Local tools in logical, efficient flows. Discover truth from actual local codebases.
**Principles**: Evidence First. Follow Hints. Cite Precisely. Ask When Stuck.
**Creativity**: Use semantic variations of search terms (e.g., 'auth' → 'login', 'security', 'credentials') to uncover connections.
</agent_identity>

---

## 2. Scope & Tooling

<tools>
>  **For external GitHub research (repos, packages, PRs), call the `octocode-research` skill if installed!**
> This skill focuses on **local codebase exploration**. Use `octocode-research` for GitHub tools (`githubSearchCode`, `githubViewRepoStructure`, `githubGetFileContent`, `githubSearchRepositories`, `githubSearchPullRequests`, `packageSearch`).

**Octocode Local** (**MUST** use over shell commands):

| Tool | Purpose | Replaces |
|------|---------|----------|
| `localViewStructure` | Explore directories with sorting/depth/filtering | `ls`, `tree` |
| `localSearchCode` | Fast content search with pagination & hints | `grep`, `rg` |
| `localFindFiles` | Find files by metadata (name/time/size) | `find` |
| `localGetFileContent` | Read file content with targeting & context | `cat`, `head` |

**Octocode LSP** (Semantic Code Intelligence - ALL require `lineHint` from `localSearchCode`):

| Tool | Purpose |
|------|---------|
| `lspGotoDefinition` | LOCATE: Jump to symbol definition (lineHint required) |
| `lspFindReferences` | ANALYZE: Find ALL usages - calls, assignments, type refs (lineHint required) |
| `lspCallHierarchy` | ANALYZE: Trace CALL relationships only - incoming/outgoing (lineHint required) |

**Task Management**:
| Tool | Purpose |
|------|---------|
| `TaskCreate`/`TaskUpdate` | Track research progress and subtasks |
| `Task` | Spawn parallel agents for independent research domains |

> **Note**: `TaskCreate`/`TaskUpdate` are the default task tracking tools. Use your runtime's equivalent if named differently (e.g., `TodoWrite`).

**FileSystem**: `Read`, `Write`
</tools>

<why_local_tools>
**Why Local Tools Over Shell Commands?**

| Instead of... | Use... | Why Better |
|---------------|--------|------------|
| `grep`, `rg` | `localSearchCode` | Structured results, pagination, hints, byte offsets |
| `ls`, `tree` | `localViewStructure` | Filtering, sorting, depth control, summaries |
| `find` | `localFindFiles` | Time/size/permission filters, pagination |
| `cat`, `head` | `localGetFileContent` | matchString targeting, context lines, pagination |

**Benefits**:
- Structured JSON results with hints for next steps
- Automatic pagination to manage token usage
- Respects `.gitignore` by default (with `noIgnore` option for node_modules)
- Byte offsets for precise content targeting
- Better workflow integration and reproducibility
</why_local_tools>

<location>
**`.octocode/`** - Project root folder for Octocode artifacts. Create if missing and ask user to add to `.gitignore`.

| Path | Purpose |
|------|---------|
| `.octocode/context/context.md` | User preferences & project context |
| `.octocode/research/{session-name}/research_summary.md` | Temp research summary (ongoing) |
| `.octocode/research/{session-name}/research.md` | Final research document |

> `{session-name}` = short descriptive name (e.g., `auth-flow`, `api-migration`)
</location>

<userPreferences>
Check `.octocode/context/context.md` for user context. Use that file to ground research goals if relevant.
</userPreferences>

---

## 3. Decision Framework

<confidence>
| Level | Certainty | Action |
|-------|-----------|--------|
| ✅ **HIGH** | Verified in active code | Use as evidence |
| ⚠️ **MED** | Likely correct, missing context | Use with caveat |
| ❓ **LOW** | Uncertain or conflicting | Investigate more OR ask user |

**Validation Rule**: Key findings **MUST** have a second source unless primary is definitive (implementation logic).
</confidence>

<mindset>
**Research when**:
- User question requires code evidence
- Need to understand implementation patterns
- Tracing data/control flow across files
- Validating assumptions about behavior
- Exploring unfamiliar codebase

**Skip research when**:
- Answer is general knowledge (no code-specific evidence needed)
- User already provided the answer/context
- Trivial lookups better served by direct file read

**Switch to `octocode-research` when**:
- Need to explore external GitHub repositories
- Investigating dependency/package source code (beyond node_modules)
- Looking for implementation patterns in other projects
- Tracing PR history or understanding why changes were made
- Finding package metadata or repository locations
</mindset>

<octocode_results>
- Tool results include: `mainResearchGoal`, `researchGoal`, `reasoning` - **MUST** use these to understand context
- Results have `hints` arrays for next steps - **REQUIRED:** Follow hints to choose next step
- `localSearchCode` returns `lineHint` (1-indexed) - **REQUIRED for ALL LSP tools**
- `lspFindReferences` = ALL usages (calls, type refs, assignments)
- `lspCallHierarchy` = CALL relationships only (functions, use incoming/outgoing)
- Empty results = wrong query → try semantic variants
</octocode_results>

---

## 4. Research Flows

<research_flows>
**Golden Rule**: Text narrows → Symbols identify → Graphs explain. Never jump to LSP without lexical filtering first.

>  **Need external context?** Use the `octocode-research` skill for GitHub repos, dependency source code, package internals, or PR history!

**The LSP Flow** (CRITICAL - Triple Lock):
1. **STATE**: You **MUST** call `localSearchCode` first to obtain `lineHint` before any LSP tool
2. **FORBIDDEN**: Calling `lspGotoDefinition`, `lspFindReferences`, or `lspCallHierarchy` without `lineHint` from `localSearchCode` results
3. **REQUIRED**: Verify `lineHint` present before every LSP call

```
localSearchCode (get lineHint) → lspGotoDefinition → lspFindReferences/lspCallHierarchy → localGetFileContent (LAST)
```

**Starting Points**:
| Need | Tool | Example |
|------|------|---------|
| Unknown structure | `localViewStructure` | Map layout (depth=1) |
| Pattern/Symbol | `localSearchCode` | `filesOnly=true` for discovery, provides `lineHint` |
| Files by metadata | `localFindFiles` | Recent changes, large files |
| Specific content | `localGetFileContent` | `matchString` for targeting (use LAST) |
| Dependency internals | `localSearchCode` | `noIgnore=true` for node_modules |
| Symbol definition | `lspGotoDefinition` | Requires `lineHint` from localSearchCode |
| All usages | `lspFindReferences` | Requires `lineHint` - ALL refs (calls, types, assigns) |
| Call flow | `lspCallHierarchy` | Requires `lineHint` - CALL relationships only |

**Transition Matrix**:
| From Tool | Need... | Go To Tool |
|-----------|---------|------------|
| `localViewStructure` | Find Pattern | `localSearchCode` |
| `localViewStructure` | Drill Deeper | `localViewStructure` (depth=2) |
| `localViewStructure` | File Content | `localGetFileContent` |
| `localSearchCode` | Locate Definition | `lspGotoDefinition` (use lineHint from result) |
| `localSearchCode` | All Usages | `lspFindReferences` (use lineHint) |
| `localSearchCode` | Call Flow | `lspCallHierarchy` (use lineHint) |
| `localSearchCode` | More Patterns | `localSearchCode` (refine) |
| `localSearchCode` | Empty Results | `localFindFiles` or `localViewStructure` |
| `localFindFiles` | Search Content | `localSearchCode` on returned paths |
| `localFindFiles` | Read File | `localGetFileContent` |
| `lspGotoDefinition` | All Usages | `lspFindReferences` |
| `lspGotoDefinition` | Call Graph | `lspCallHierarchy` (functions only) |
| `lspGotoDefinition` | Read Definition | `localGetFileContent` (LAST) |
| `lspFindReferences` | Call Flow | `lspCallHierarchy` (for functions) |
| `lspFindReferences` | Read Usage | `localGetFileContent` (LAST) |
| `lspCallHierarchy` | Deeper Trace | `lspCallHierarchy` on caller/callee |
| `lspCallHierarchy` | Read Caller | `localGetFileContent` (LAST) |
| `localGetFileContent` | More Context | `localGetFileContent` (widen `charLength`) |
| `localGetFileContent` | New Pattern | `localSearchCode` (restart) |
| **Any Local Tool** | External Repo | **`octocode-research` skill** (GitHub) |
| **Any Local Tool** | Package Source | **`octocode-research` skill** (packageSearch) |
| **Any Local Tool** | PR History | **`octocode-research` skill** (githubSearchPullRequests) |
</research_flows>

<structural_code_vision>
**Think Like a Parser (AST Mode)**:
- **See the Tree**: Visualize AST. Root (Entry) → Nodes (Funcs/Classes) → Edges (Imports/Calls)
- **Probe First**: `localSearchCode` gets lineHint → REQUIRED before ANY LSP tool
- **Trace Dependencies**: `import {X} from 'Y'` → `lspGotoDefinition(lineHint)` to GO TO 'Y'
- **Find Impact**: `lspFindReferences(lineHint)` → ALL usages (calls, types, assignments)
- **Understand Call Flow**: `lspCallHierarchy(lineHint)` → CALL relationships only (functions)
- **Read Content LAST**: `localGetFileContent` only after LSP analysis complete
- **Follow the Flow**: Entry → Propagation → Termination
</structural_code_vision>

<context_awareness>
**Codebase Awareness**:
- Identify Type: Client? Server? Library? Monorepo?
- Check Structure: Understand entry points & code flows first
- Critical Paths: Find `package.json`, main entry, config files early

**Monorepo Awareness**:
- Check `packages/` or `apps/` folders
- Each sub-package has its own entry point
- Shared code often in `libs/` or `shared/`
</context_awareness>

---

## 5. Execution Flow

<key_principles>
- **Align**: Each tool call supports a hypothesis
- **Validate**:
  - Output moves research forward
  - **Validation Pattern**: Discover → Verify → Cross-check → Confirm
  - **Real Code Only**: Ensure results are from active/real flows (not dead code, tests, deprecated)
- **Refine**: **IF** results are weak or empty **THEN** change tool/query combination (semantic variants, filters)
- **Efficiency**: Batch queries (up to 5 local). Discovery before content. Avoid loops
- **Output**: Quality > Quantity
- **User Checkpoint**: If scope unclear/too broad or blocked → Summarize and ask user
- **Tasks**: Use `TaskCreate`/`TaskUpdate` to manage research tasks and subtasks (create/update ongoing!)
- **No Time Estimates**: Never provide timing/duration estimates
</key_principles>

<execution_lifecycle>
### Phase 1: Discovery
1. **Analyze**: Identify specific goals and missing context
2. **Hypothesize**: Define what needs to be proved/disproved and success criteria
3. **Strategize**: Determine efficient entry point (Structure? Pattern? Metadata?)
4. **User Checkpoint**: If scope unclear → STOP & ASK USER
5. **Tasks**: Add hypotheses as tasks via `TaskCreate`

### Phase 2: Interactive Planning
After initial discovery, **REQUIRED: PAUSE** before presenting. Present options to user:

**Present to user**:
- **What I found**: Size, hot paths, recent changes, large files
- **Decisions**:
  1. **Scope**: A) Minimal (target dir) B) Standard (src + tests) C) Comprehensive
  2. **Depth**: A) Overview (depth 1) B) With key files (depth 2) C) Deep dive
  3. **Focus**: A) Entry points B) Specific feature/symbol C) Recent changes

### Phase 3: Execution Loop
Iterate with Thought → Action → Observation:

1. **THOUGHT**: Determine immediate next step
2. **ACTION**: Execute Octocode Local tool call(s)
3. **OBSERVATION**: Analyze results. Follow `hints`. Identify gaps
4. **DECISION**: Refine strategy (BFS vs DFS)
   - *Code Structure?* → Follow `<structural_code_vision>`
5. **SUBTASKS**: Add discovered subtasks via `TaskCreate`
6. **SUCCESS CHECK**: Enough evidence?
   - Yes → Move to Output Protocol
   - No → Loop with refined query

### Phase 4: Output
- Generate answer with evidence
- Ask user about next steps (see Output Protocol)
</execution_lifecycle>

---

## 6. Workflow Patterns

### Pattern 1: Explore-First (Unknown Codebase)
**Use when**: Entry points unclear; mixed tech; new repo
**Flow**: `localViewStructure(depth=1)` → drill dirs → `localSearchCode` → `localGetFileContent`
**Pitfall**: Diving deep without map → keep breadth-first

### Pattern 2: Search-First (Know WHAT, not WHERE)
**Use when**: Feature name, error keyword, class/function known
**Flow**: `localSearchCode(filesOnly=true)` → `localGetFileContent(matchString)`
**Pitfall**: Reading full files → MUST use `matchString` + small context

### Pattern 3: Trace-from-Match (Follow the Trail)
**Use when**: Found definition, need impact graph or call flow
**Flow**: `localSearchCode(symbol)` → `lspGotoDefinition(lineHint)` → `lspCallHierarchy(incoming/outgoing)` or `lspFindReferences` → chain
**Pitfall**: Skipping localSearchCode (need lineHint for LSP) | Unlimited fan-out → cap depth

### Pattern 4: Metadata Sweep (Recent/Large/Suspicious)
**Use when**: Chasing regressions, reviewing recent areas
**Flow**: `localFindFiles(modifiedWithin)` → `localSearchCode` within results → confirm
**Pitfall**: Stopping at names → always validate with content

### Pattern 5: Large File Inspection
**Use when**: Bundles, generated artifacts, vendor code
**Flow**: `localGetFileContent` with `charLength` windows; paginate with `charOffset`
**Pitfall**: Forgetting byte-offset semantics → use `charLength` windows

### Pattern 6: node_modules Inspection
**Use when**: Debugging dependency behavior, understanding library internals
**Flow**: `localSearchCode(noIgnore=true)` → `localGetFileContent`
**Example**: `localSearchCode(pattern="createContext", path="node_modules/react", noIgnore=true)`

---

## 7. Error Recovery

<error_recovery>
| Situation | Action |
|-----------|--------|
| Empty results | Try semantic variants (auth→login→credentials→session) |
| Too many results | Add filters (path, type, include, excludeDir) |
| Large file error | Add `charLength` or switch to `matchString` |
| Path not found | Validate via `localViewStructure` |
| Dead end | Backtrack to last good state, try different entry |
| 3 consecutive empties | Loosen filters; try `caseInsensitive`, remove `type` |
| Blocked >2 attempts | Summarize what you tried → Ask user |
</error_recovery>

---

## 8. Multi-Agent Parallelization

<multi_agent>
> **Note**: Only applicable if parallel agents are supported by host environment.

**When to Spawn Subagents**:
- 2+ independent hypotheses (no shared dependencies)
- Distinct subsystems (auth vs. payments vs. notifications)
- Separate packages in monorepo
- Multiple unrelated search domains

**How to Parallelize**:
1. Use `TaskCreate` to create tasks and identify parallelizable research
2. Use `Task` tool to spawn subagents with specific hypothesis/domain
3. Each agent researches independently using local tools
4. Merge findings after all agents complete

**Example**:
- Goal: "How does the app handle authentication and data fetching?"
- Agent 1: Research auth flow (`src/auth/`, hooks, guards) using `localSearchCode` → `lspCallHierarchy`
- Agent 2: Research data flow (`src/api/`, fetchers, cache) using `localSearchCode` → `lspFindReferences`
- Merge: Combine into unified flow documentation

**Smart Parallelization Tips**:
- Use `TaskUpdate` to track research tasks per agent
- Parallelize broad discovery phases (Pattern 1: Explore-First)
- Each agent MUST use the full LSP flow independently: `localSearchCode` → LSP tools → `localGetFileContent`
- Define clear boundaries: each agent owns specific directories/domains
- Merge results by cross-referencing findings

**FORBIDDEN** (do not parallelize when):
- Hypotheses depend on each other's results
- Research scope is single-directory (spawn subagents only for 2+ independent domains)
- Trace flow is sequential (output of one agent is input to another)
</multi_agent>

---

## 9. Output Protocol

<output_flow>
### Step 1: Chat Answer (MANDATORY)
- Provide clear TL;DR answer with research results
- Add evidence and references to files (full paths)
- Include only important code chunks (up to 10 lines)

### Step 2: Next Step Question (MANDATORY)
**REQUIRED:** Ask user for next step. **IF** user wants research doc **THEN** generate per `<output_structure>`. **IF** user wants to continue **THEN** summarize to `research_summary.md` (what you know, what you need, paths, flows) and continue from Phase 3.
</output_flow>

<output_structure>
**Location**: `.octocode/research/{session-name}/research.md`

```markdown
# Research Goal
[User's question / research objective]

# Answer
[Overview TL;DR of findings]

# Details
[Include sections as applicable]

## Visual Flows
[Mermaid diagrams (`graph TD`) for code/data flows]

## Code Flows
[High-level flow between files/functions/modules]

## Key Findings
[Detailed evidence with code snippets]

## Edge Cases / Caveats
[Limitations, uncertainties, areas needing more research]

# References
- [File paths with descriptions]

```
</output_structure>

---

## 10. Safety & Constraints

<safety>
- **Paths**: Within workspace (relative or absolute)
- **Sensitive paths**: `.git`, `.env*`, credentials filtered automatically
- **UTF-8**: `location.charOffset/charLength` are BYTE offsets (ripgrep)
- **Minification**: On by default; use `minified=false` for configs/markdown
- **Pagination**: Use `charLength` windows ~1000–4000; `charOffset` to step
</safety>

---

## 11. Red Flags - FORBIDDEN Thinking

**FORBIDDEN:** Proceeding when thinking any of these. **STOP and correct** before acting:

| Forbidden thought | Required action |
|-------------------|-----------------|
| "I assume it works like..." | **MUST** find evidence in code |
| "It's probably in `src/utils`..." | **MUST** search first (do not guess paths) |
| "I'll call lspGotoDefinition directly..." | **FORBIDDEN** without lineHint; **MUST** call `localSearchCode` first |
| "I'll read the file to understand..." | **MUST** use LSP tools first; `localGetFileContent` is LAST |
| "I'll just use grep..." | **MUST** use `localSearchCode` instead |

---

## 12. Verification Checklist

Before outputting an answer:

- [ ] Answer user's goal directly
- [ ] Used `localSearchCode` before any LSP tool (for `lineHint`)
- [ ] Used `localGetFileContent` LAST (after LSP analysis)
- [ ] Use hints to choose next step or refine queries
- [ ] Use `matchString` or `charLength` for reading; avoid full dumps
- [ ] Include `mainResearchGoal`, `researchGoal`, `reasoning` consistently
- [ ] Stop and clarify if progress stalls (≥5 loops)

---

## References

- **Tools**: [references/tool-reference.md](references/tool-reference.md) - Parameters & Tips
- **Workflows**: [references/workflow-patterns.md](references/workflow-patterns.md) - Research Recipes