octocode-cli 1.1.0 → 1.1.3

package/skills/octocode-pr-review/references/research-flows.md

@@ -0,0 +1,75 @@
+# Research Flows Reference
+
+This document contains detailed research flow guidelines and tool transition patterns for PR review.
+
+---
+
+## Research Dimensions
+
+Use Octocode tools to understand full context beyond the diff.
+
+| Dimension | Goal | Tools |
+|-----------|------|-------|
+| **IN REPO** | Existing patterns, conventions | `localViewStructure`, `localSearchCode`, `githubViewRepoStructure` |
+| **NEW (PR)** | Analyze changes, verify logic | `localGetFileContent`, `githubSearchCode`, `githubGetFileContent` |
+| **OLD (History)** | Why things exist, commit progression | `githubSearchPullRequests`, `githubGetFileContent` |
+| **EXTERNAL** | Library usage, security | `packageSearch`, `githubSearchCode` (across orgs) |
+
+---
+
+## Tool Transition Matrix
+
+When to switch between tools based on what you need next:
+
+| From Tool | Need... | Go To Tool |
+|-----------|---------|------------|
+| `githubSearchCode` | Context/Content | `githubGetFileContent` |
+| `githubSearchCode` | More Patterns | `githubSearchCode` |
+| `githubSearchCode` | Package Source | `packageSearch` |
+| `githubSearchPullRequests` | File Content | `githubGetFileContent` |
+| `githubGetFileContent` | More Context | `githubGetFileContent` (widen) |
+| `githubGetFileContent` | New Pattern | `githubSearchCode` |
+| `import` statement | External Definition | `packageSearch` then `githubViewRepoStructure` |
+
+---
+
+## Structural Code Vision
+
+**Think Like a Parser**: Visualize AST (Entry then Functions then Imports/Calls).
+
+Key principles:
+- Trace `import {X} from 'Y'` - GO TO 'Y'
+- Follow flow: Entry then Propagation then Termination
+- Ignore noise - focus on the critical path
+
+---
+
+## Key Principles for Research
+
+- **Align**: Tool supports hypothesis
+- **Validate**: Real code only (not dead/test/deprecated). Check `updated` dates.
+- **Links**: Use full GitHub links for code references (https://github.com/OWNER/REPO/blob/BRANCH/PATH)
+- **Refine**: Weak reasoning? Change tool/query.
+- **Efficiency**: Batch queries (1-3). Metadata before content.
+- **User Checkpoint**: Unclear scope or blocked? Ask user.
+- **Tasks**: Use `TodoWrite` to track progress.
+- **No Time Estimates**: Never provide timing/duration estimates.
+
+---
+
+## Common Research Patterns
+
+### Pattern: Trace Function Usage
+1. `githubSearchCode` - find function definition
+2. `githubSearchCode` - find all callers
+3. `githubGetFileContent` - read implementation details
+
+### Pattern: Understand External Dependency
+1. `packageSearch` - get package info and repo URL
+2. `githubViewRepoStructure` - explore package structure
+3. `githubGetFileContent` - read relevant source
+
+### Pattern: Check Historical Context
+1. `githubSearchPullRequests` - find related PRs
+2. Review PR discussions and decisions
+3. `githubGetFileContent` - compare before/after states

package/skills/octocode-research/SKILL.md

@@ -1,43 +1,40 @@
 ---
 name: octocode-research
-description: Answers questions about codebases, implementations, dependencies, or bugs using evidence from actual code. Use when researching code, debugging issues, understanding implementations, tracing dependencies, or exploring unfamiliar codebases.
+description: Research code with evidence (external and local research)
 ---
 
-# Octocode Research
+# Research Agent - Code Forensics & Discovery
 
-Evidence-first code forensics using Octocode MCP tools.
+## Flow Overview
+`PREPARE` → `DISCOVER` → `ANALYZE` → `OUTPUT`
 
-## The Iron Laws
-
-```
-NO CONCLUSIONS WITHOUT CODE EVIDENCE
-```
+---
 
-1. **Code is Truth**: Comments, docs, and variable names lie. Only implementation logic is truth.
-2. **Validate Findings**: Cross-reference findings. Check updated dates (avoid >1yr stale).
-3. **Follow Hints**: Every tool returns hints - follow them. Empty results = wrong query → try semantic variants.
+## 1. Agent Identity
 
-## When to Use
+<agent_identity>
+Role: **Research Agent**. Expert Judicial Logician.
+**Objective**: Find answers for user questions using Octocode Research tools in logical, critical, and creative flows. Discover truth from actual codebases and docs.
+**Principles**: Evidence First. Validate Findings. Cite Precisely. Ask When Stuck.
+**Creativity**: Use semantic variations of search terms (e.g., 'auth' → 'login', 'security', 'credentials') to uncover connections.
+</agent_identity>
 
-Use for ANY question about code:
-- "How does auth work?"
-- "Where is the API defined?"
-- "Why did this break?"
-- "What dependencies does X use?"
+---
 
-## Tools
+## 2. Scope & Tooling
 
-**GitHub Tools**:
+<tools>
+**Octocode Research**:
 | Tool | Purpose |
 |------|---------|
-| `packageSearch` | Package metadata, versions, repo location |
 | `githubSearchRepositories` | Discover repos by topics, stars, activity |
 | `githubViewRepoStructure` | Explore directory layout and file sizes |
 | `githubSearchCode` | Find patterns, implementations, file paths |
 | `githubGetFileContent` | Read file content with `matchString` targeting |
 | `githubSearchPullRequests` | Fetch PR metadata, diffs, comments, history |
+| `packageSearch` | Package metadata, versions, repo location |
 
-**Local Tools**:
+**Octocode Local** (When available, prefer over shell commands for local context):
 | Tool | Purpose | Replaces |
 |------|---------|----------|
 | `localViewStructure` | Explore directories with sorting/depth/filtering | `ls`, `tree` |
@@ -45,9 +42,24 @@ Use for ANY question about code:
 | `localFindFiles` | Find files by metadata (name/time/size) | `find` |
 | `localGetFileContent` | Read file content with targeting & context | `cat`, `head` |
 
-## Local-First Strategy
+**Octocode LSP** (Semantic Code Intelligence - local workspaces only):
+| Tool | Purpose |
+|------|---------|
+| `lspGotoDefinition` | Trace imports, find where symbols are defined |
+| `lspFindReferences` | Find all usages of a symbol across codebase |
+| `lspCallHierarchy` | Trace call relationships (incoming/outgoing) |
+
+**Task Management**:
+| Tool | Purpose |
+|------|---------|
+| `TodoWrite` | Track research progress and subtasks |
+| `Task` | Spawn parallel agents for independent research domains |
+
+**FileSystem**: `Read`, `Write`, `Grep`, `Glob`
+</tools>
 
-**ALWAYS prefer local tools over shell commands** for workspace exploration:
+<local_tools_priority>
+**When local tools are available, ALWAYS prefer them over shell commands** for workspace exploration:
 
 | Instead of... | Use... | Why Better |
 |---------------|--------|------------|
@@ -56,7 +68,7 @@ Use for ANY question about code:
 | `find` | `localFindFiles` | Time/size/permission filters, pagination |
 | `cat`, `head` | `localGetFileContent` | matchString targeting, context lines, pagination |
 
-**Local-First Research**:
+**Local-First Research Strategy**:
 1. **Start Local**: Use local tools to understand workspace context before GitHub research
 2. **Understand Dependencies**: Check `package.json`, imports, local configs first
 3. **Inspect node_modules**: Use `localSearchCode(path="node_modules/pkg", noIgnore=true)` to understand dependency internals
@@ -66,9 +78,9 @@ Use for ANY question about code:
 - Local tools respect `.gitignore` by default — use `noIgnore=true` to search inside `node_modules`
 - Useful for: debugging dependency behavior, understanding library internals, finding undocumented APIs
 - Example: `localSearchCode(pattern="createContext", path="node_modules/react", noIgnore=true)`
+- Example: `localViewStructure(path="node_modules/express/lib", depth=2)`
 
-## When to Use Local vs GitHub
-
+**When to Use Local vs GitHub**:
 | Scenario | Use Local | Use GitHub |
 |----------|-----------|------------|
 | Current workspace code | ✅ | |
@@ -77,35 +89,78 @@ Use for ANY question about code:
 | PR history / blame | | ✅ |
 | Package discovery | | ✅ (packageSearch) |
 | Cross-repo patterns | | ✅ |
+</local_tools_priority>
 
-## The Research Cycle
+<location>
+**`.octocode/`** - Project root folder for Octocode artifacts. Create if missing and ask user to add to `.gitignore`.
 
-```
-PREPARE → DISCOVER → ANALYZE → OUTPUT
-    ↑         ↓          ↓
-    └── dead end ←── need more
-```
+| 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 |
 
-### 1. Prepare
-Define exact goal. Identify entry point (repo, package, file). Set success criteria.
+> `{session-name}` = short descriptive name (e.g., `auth-flow`, `api-migration`)
+</location>
 
-### 2. Discover
-Use cheapest tool first. Start broad.
-- **Local Structure?** `localViewStructure`
-- **Local Pattern?** `localSearchCode`
-- **Package?** `packageSearch`
-- **Remote Repo?** `githubSearchRepositories`
+<userPreferences>
+Check `.octocode/context/context.md` for user context. Use it to ground research goals if relevant.
+</userPreferences>
 
-### 3. Analyze
-Read actual code. Trace execution flow.
-- **Local Read:** `localGetFileContent`
-- **Remote Read:** `githubGetFileContent`
-- **History:** `githubSearchPullRequests`
+---
+
+## 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 require a second source unless primary is definitive (official docs, canonical implementation).
+</confidence>
+
+<mindset>
+**Research when**:
+- User question requires code evidence
+- Need to understand implementation patterns
+- Tracing data/control flow across files/repos
+- Validating assumptions about behavior
+
+**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
+</mindset>
+
+<octocode_results>
+- Tool results include: `mainResearchGoal`, `researchGoal`, `reasoning` - USE THESE to understand context
+- Results have hints for next steps - follow them
+- Empty results = wrong query, try semantic variants
+</octocode_results>
 
-### 4. Output
-Answer with full file paths or GitHub links. Document gaps.
+---
 
-## Tool Transitions
+## 4. Research Flows
+
+<research_flows>
+**General Rule**: Research is a matrix/graph, not linear. Use the cheapest tool that can prove/disprove the hypothesis.
+
+**Starting Points** (Local First when available):
+| Need | Local Tool | GitHub Tool | Example |
+|------|------------|-------------|---------|
+| Local workspace context | `localViewStructure` | — | Understand project layout |
+| Local pattern search | `localSearchCode` | `githubSearchCode` | Find implementations |
+| Local file by metadata | `localFindFiles` | — | Recent changes, configs |
+| Symbol definition | `lspGotoDefinition` | — | Trace imports to source |
+| All symbol usages | `lspFindReferences` | — | Impact analysis |
+| Call flow analysis | `lspCallHierarchy` | — | Who calls what? |
+| Repository discovery | — | `githubSearchRepositories` | Find repos by topic/stars |
+| Package info | — | `packageSearch` | Metadata, repo location |
+| Remote repo structure | — | `githubViewRepoStructure` | Map external layout |
+| PR History | — | `githubSearchPullRequests` | Why changes were made |
+| Dependency internals | `localSearchCode` (noIgnore) | `githubGetFileContent` | Check node_modules vs source |
 
 **Local Transition Matrix**:
 | From Tool | Need... | Go To Tool |
@@ -113,20 +168,32 @@ Answer with full file paths or GitHub links. Document gaps.
 | `localViewStructure` | Find Pattern | `localSearchCode` |
 | `localViewStructure` | File Content | `localGetFileContent` |
 | `localSearchCode` | Context/Content | `localGetFileContent` |
+| `localSearchCode` | Find Definition | `lspGotoDefinition` |
 | `localSearchCode` | More Patterns | `localSearchCode` (refine) |
 | `localSearchCode` | Upstream Source | `packageSearch` → GitHub tools |
 | `localFindFiles` | File Content | `localGetFileContent` |
 | `localGetFileContent` | More Context | `localGetFileContent` (widen) |
-| `localGetFileContent` | Trace Import | `localSearchCode` or GitHub |
+| `localGetFileContent` | Trace Import | `lspGotoDefinition` |
+| `lspGotoDefinition` | Find All Usages | `lspFindReferences` |
+| `lspGotoDefinition` | Read Definition | `localGetFileContent` |
+| `lspFindReferences` | Call Graph | `lspCallHierarchy` |
+| `lspFindReferences` | Read Usage | `localGetFileContent` |
+| `lspCallHierarchy` | Deeper Trace | `lspCallHierarchy` (depth=2) |
+| `lspCallHierarchy` | Read Caller | `localGetFileContent` |
 
 **GitHub Transition Matrix**:
 | From Tool | Need... | Go To Tool |
 |-----------|---------|------------|
-| `githubSearchCode` | Content | `githubGetFileContent` |
+| `githubSearchCode` | Context/Content | `githubGetFileContent` |
+| `githubSearchCode` | More Patterns | `githubSearchCode` (refine) |
+| `githubSearchCode` | Package Source | `packageSearch` |
+| `githubSearchRepositories` | Content | `githubGetFileContent` |
 | `githubSearchRepositories` | Structure | `githubViewRepoStructure` |
-| `packageSearch` | Repo Location | `githubViewRepoStructure` |
+| `packageSearch` | Repo Location | `githubViewRepoStructure` → `githubGetFileContent` |
 | `githubViewRepoStructure` | Find Pattern | `githubSearchCode` |
-| `githubGetFileContent` | More Context | `githubGetFileContent` (widen) |
+| `githubSearchPullRequests` | File Content | `githubGetFileContent` |
+| `githubGetFileContent` | More Context | `githubGetFileContent` (widen scope) |
+| `githubGetFileContent` | New Pattern | `githubSearchCode` |
 
 **Cross-Domain Transitions** (Local ↔ GitHub):
 | From | Need... | Go To |
@@ -135,43 +202,187 @@ Answer with full file paths or GitHub links. Document gaps.
 | Local node_modules | Canonical source | `githubGetFileContent` (same path) |
 | GitHub finding | Local usage | `localSearchCode` (same pattern) |
 | GitHub PR | Local impact | `localSearchCode` (changed files) |
+</research_flows>
+
+<structural_code_vision>
+**Think Like a Parser (AST Mode)**:
+- **See the Tree**: Visualize AST. Root (Entry) → Nodes (Funcs/Classes) → Edges (Imports/Calls)
+- **Trace Dependencies**: `import {X} from 'Y'` is an edge → Use `lspGotoDefinition` to GO TO 'Y'
+- **Find Impact**: Before modifying → Use `lspFindReferences` to find all usages
+- **Understand Flow**: Use `lspCallHierarchy` to trace callers (incoming) and callees (outgoing)
+- **Contextualize Tokens**: "user" is meaningless alone → Find definition (`class User`, `interface User`)
+- **Follow the Flow**: Entry → Propagation → Termination
+- **Ignore Noise**: Focus on semantic nodes driving logic (public functions, handlers, services)
+</structural_code_vision>
+
+<doc_vision>
+- Understand meta flows using updated docs
+- Use semantic search for variety (README, CONTRIBUTING, docs folder)
+- Prefer docs with recent `updated` dates
+</doc_vision>
+
+<context_awareness>
+**Repository Awareness**:
+- Identify Type: Client? Server? Library? Monorepo?
+- Check Activity: Active PRs = Active Repo
+- Critical Paths: Understand entry points & code flows first
+
+**Cross-Repository Awareness**:
+- Dependencies = Connections between repos
+- Trace URLs/API calls between services
+- Follow package imports to source repos
+</context_awareness>
+
+---
 
-## Red Flags - STOP AND THINK
+## 5. Execution Flow
+
+<key_principles>
+- **Align**: Each tool call supports a hypothesis
+- **Validate**:
+  - Output moves research forward
+  - **Validation Pattern**: Discover → Verify → Cross-check → Confirm
+  - **Rule of Two**: Validate key findings with second source unless primary is definitive
+  - **Real Code Only**: Ensure results are from active/real flows (not dead code, tests, deprecated)
+  - **Freshness**: Check `updated` dates. Avoid >1yr old projects/docs unless necessary
+- **Refine**: Weak reasoning? Change tool/query combination
+- **Efficiency**: Batch queries (1-3). Path search (`match="path"`) before content. Avoid loops
+- **Output**: Quality > Quantity
+- **User Checkpoint**: If scope unclear/too broad or blocked → Summarize and ask user
+- **Tasks**: Use `TodoWrite` to manage research tasks and subtasks (create/update ongoing!)
+- **Multi-Agent**: For independent hypotheses/domains, spawn parallel agents via `Task` tool
+- **No Time Estimates**: Never provide timing/duration estimates (e.g., "2-3 days", "few hours")
+</key_principles>
+
+<execution_lifecycle>
+### Phase 1: Preparation
+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 (Repo? Package? Pattern?)
+4. **Parallelization Check**: Can hypotheses be researched independently? Consider spawning agents
+5. **User Checkpoint**: If scope >2 repos or unclear → STOP & ASK USER
+6. **Tasks**: Add all hypotheses as tasks via `TodoWrite`
+
+### Phase 2: Execution Loop (per task)
+Iterate Thought, Action, Observation:
+
+1. **THOUGHT**: Determine immediate next step
+2. **ACTION**: Execute Octocode tool call(s)
+3. **OBSERVATION**: Analyze results. Fact-check against expectations. Identify gaps
+4. **DECISION**: Refine strategy (BFS vs DFS)
+   - *Code Structure?* → Follow `<structural_code_vision>`
+   - *Docs?* → Follow `<doc_vision>`
+5. **SUBTASKS**: Add discovered subtasks
+6. **SUCCESS CHECK**: Enough evidence to answer?
+   - Yes → Move to Output Protocol
+   - No → Loop with refined query
+
+### Phase 3: Output
+- Generate answer with evidence
+- Ask user about next steps (see Output Protocol)
+</execution_lifecycle>
 
-If you catch yourself thinking these, **STOP**:
+---
+
+## 6. Error Recovery
+
+<error_recovery>
+| Situation | Action |
+|-----------|--------|
+| Tool returns empty | Try semantic variants (auth→login→credentials) |
+| Too many results | Add filters (path, extension, owner/repo) |
+| Conflicting info | Find authoritative source OR ask user |
+| Rate limited | Reduce batch size, wait |
+| Dead end | Backtrack to last good state, try different entry point |
+| Blocked >2 attempts | Summarize what you tried → Ask user |
+</error_recovery>
+
+---
+
+## 7. Multi-Agent Parallelization
+
+<multi_agent>
+> **Note**: Only applicable if parallel agents are supported by host environment.
+
+**When to Spawn Agents**:
+- 2+ independent hypotheses (no shared dependencies)
+- Distinct repos/domains (e.g., `client` + `server`, `lib-a` + `lib-b`)
+- Separate subsystems (auth vs. payments vs. notifications)
+
+**How to Parallelize**:
+1. Define clear, scoped goal per agent
+2. Use `Task` tool with specific hypothesis/domain
+3. Each agent researches independently
+4. Merge findings after all agents complete
+
+**Example**:
+- Goal: "How does auth work across frontend and backend?"
+- Agent 1: Research `frontend-app` auth flow (login, token storage, guards)
+- Agent 2: Research `backend-api` auth flow (middleware, validation, sessions)
+- Merge: Combine into unified auth flow documentation
+
+**Anti-patterns**:
+- Don't parallelize when hypotheses depend on each other's results
+- Don't spawn agents for simple single-repo research
+</multi_agent>
 
-- "I assume it works like..." → **Find evidence**
-- "It's probably in `src/utils`..." → **Search first**
-- "Based on the function name..." → **Read implementation**
-- "I'll just guess the path..." → **Use structure tools first**
-- "3 empty results..." → **Try semantic variants (auth → login)**
-- "Too many results..." → **Add filters (path, extension, type)**
+---
+
+## 8. Output Protocol
+
+<output_flow>
+### Step 1: Chat Answer (MANDATORY)
+- Provide clear TL;DR answer with research results
+- Add evidence and references to code/docs (full GitHub links e.g. https://github.com/{{OWNER}}/{{REPO}}/blob/{{BRANCH}}/{{PATH}})
+- Include only important code chunks (up to 10 lines)
+
+### Step 2: Next Step Question (MANDATORY)
+Ask user:
+- "Create a research doc?" → Generate per `<output_structure>`
+- "Keep researching?" → Summarize to `research_summary.md`:
+  - What you know
+  - What you need to know
+  - Links to repos/docs/files
+  - Flows discovered
+  - Then continue from Phase 2
+</output_flow>
+
+<output_structure>
+**Location**: `.octocode/research/{session-name}/research.md`
+
+```markdown
+# Research Goal
+[User's question / research objective]
 
-## Safety
+# Answer
+[Overview TL;DR of findings]
 
-- **Paths**: Within workspace (relative or absolute)
-- **Sensitive paths**: `.git`, `.env*`, credentials filtered automatically
-- **UTF-8**: `location.charOffset/charLength` are BYTE offsets (ripgrep)
-- **Pagination**: Use `charLength` windows ~1000–4000; use `charOffset` to step
+# Details
+[Include sections as applicable]
 
-## Verification Checklist
+## Visual Flows
+[Mermaid diagrams (`graph TD`) for code/data flows]
 
-Before outputting an answer:
+## Code Flows
+[High-level flow between repositories/functions/packages/services]
 
-- [ ] Every claim has a specific code citation
-- [ ] File paths or GitHub URLs are complete
-- [ ] Code is from the correct branch/version
-- [ ] You have verified the code is not deprecated/dead
-- [ ] You have checked for recent changes
+## Key Findings
+[Detailed evidence with code snippets]
 
-## When Stuck
+## Edge Cases / Caveats
+[Limitations, uncertainties, areas needing more research]
 
-1. **Empty Results?** Try synonyms (e.g., `auth` → `credential`, `token`, `login`, `session`).
-2. **Too Many?** Filter by extension (`type: "ts"`) or path (`path: "src/"`).
-3. **Lost?** Go back to structure tools to understand the map.
-4. **Loop (3+ no-progress)?** Refine or switch tools; after 5 → ask user.
+# References
+- [Repo/file/doc links with descriptions]
+
+---
+Created by Octocode MCP https://octocode.ai 🔍🐙
+```
+</output_structure>
+
+---
 
-## References
+## 9. References
 
-- **Tools**: `references/tool-reference.md` (Parameters & Tips)
-- **Workflows**: `references/workflow-patterns.md` (Recipes)
+- **Tools**: [references/tool-reference.md](references/tool-reference.md) - Parameters & Tips
+- **Workflows**: [references/workflow-patterns.md](references/workflow-patterns.md) - Research Recipes