octocode-cli 1.0.0 → 1.1.0

package/skills/octocode-research/references/workflow-patterns.md

@@ -0,0 +1,325 @@
+# Workflow Patterns
+
+Common research flows for different investigation types.
+
+---
+
+## Local-First Patterns
+
+### 1. Explore-First (Unknown Codebase)
+
+**Use when**: Entry points unclear, mixed tech, new repo.
+
+```
+localViewStructure(depth=1) → drill dirs(depth=2) → localSearchCode → localGetFileContent
+```
+
+**Steps:**
+1. **Map Root**: View top-level folders (`depth: 1`)
+2. **Drill Down**: Pick one relevant folder (e.g., `src`)
+3. **Search**: Look for architectural keywords (`App`, `Server`, `Main`)
+4. **Read**: Get content of entry file
+
+```json
+// 1. Map root
+{ "path": "", "depth": 1 }
+
+// 2. Drill into src
+{ "path": "src", "depth": 2 }
+
+// 3. Find entry points
+{ "pattern": "createServer|createApp", "path": "src", "filesOnly": true }
+
+// 4. Read implementation
+{ "path": "src/index.ts", "matchString": "createApp" }
+```
+
+**Pitfall**: Diving deep without map → keep breadth-first.
+
+---
+
+### 2. Search-First (Know WHAT, not WHERE)
+
+**Use when**: Feature name, error keyword, class/function known.
+
+```
+localSearchCode(filesOnly=true) → localGetFileContent(matchString)
+```
+
+**Steps:**
+1. **Discovery**: Find files containing the term (fast)
+2. **Target**: Pick the most likely file
+3. **Read**: Read specific function with context
+
+```json
+// 1. Discovery
+{ "pattern": "AuthService", "path": "src", "type": "ts", "filesOnly": true }
+
+// 2. Read implementation
+{ "path": "src/auth/AuthService.ts", "matchString": "class AuthService", "matchStringContextLines": 20 }
+```
+
+**Pitfall**: Reading full files; prefer `matchString` + small context windows.
+
+---
+
+### 3. Trace-from-Match (Follow the Trail)
+
+**Use when**: Found definition, need impact graph (imports/usages).
+
+```
+localSearchCode(symbol) → localGetFileContent → localSearchCode(usages) → iterate
+```
+
+**Steps:**
+1. **Find Definition**: Search for the symbol
+2. **Read Implementation**: Get context
+3. **Trace Usages**: Search for imports/calls
+4. **Iterate**: Follow 1-3 focused branches (cap depth)
+
+```json
+// 1. Find definition
+{ "pattern": "export.*useAuth", "path": "src", "filesOnly": true }
+
+// 2. Read implementation
+{ "path": "src/hooks/useAuth.ts", "matchString": "export function useAuth" }
+
+// 3. Find usages
+{ "pattern": "import.*useAuth|useAuth\\(", "path": "src", "filesOnly": true }
+```
+
+**Pitfall**: Unlimited fan-out; cap depth and batch size.
+
+---
+
+### 4. Metadata-Driven (Recent Changes)
+
+**Use when**: Debugging recent breaks, finding config files, large files.
+
+```
+localFindFiles(modifiedWithin/size) → localGetFileContent
+```
+
+**Steps:**
+1. **Filter**: Find files by metadata (time, size, type)
+2. **Read**: Examine content of candidates
+
+```json
+// Find recently modified TypeScript files
+{ "path": "src", "name": "*.ts", "modifiedWithin": "7d" }
+
+// Find large files that might need attention
+{ "path": "", "sizeGreater": "100K", "type": "f" }
+```
+
+---
+
+### 5. node_modules Inspection
+
+**Use when**: Debugging dependency behavior, understanding library internals.
+
+```
+localSearchCode(noIgnore=true) → localGetFileContent → compare with GitHub source
+```
+
+**Steps:**
+1. **Search Inside**: Use `noIgnore: true` to search node_modules
+2. **Read Local**: Get content from installed version
+3. **Cross-Reference**: Compare with canonical GitHub source
+
+```json
+// 1. Search inside dependency
+{ "pattern": "createContext", "path": "node_modules/react", "noIgnore": true }
+
+// 2. Read local implementation
+{ "path": "node_modules/react/cjs/react.development.js", "matchString": "createContext" }
+
+// 3. Compare with canonical (use GitHub tools)
+```
+
+---
+
+## GitHub Patterns
+
+### 6. Package Investigation
+
+**Goal**: Understand how a package works internally.
+
+```
+packageSearch → githubViewRepoStructure → githubSearchCode → githubGetFileContent
+```
+
+**Steps:**
+1. **Locate**: Find the correct repo URL
+2. **Map**: View directory structure (don't map everything)
+3. **Entry**: Find the main entry point (`package.json` main or index file)
+4. **Read**: Get actual content of the entry file
+
+```json
+// 1. Find repo
+{ "name": "express", "ecosystem": "npm" }
+
+// 2. Map structure
+{ "owner": "expressjs", "repo": "express", "branch": "master", "depth": 1 }
+
+// 3. Find entry
+{ "keywordsToSearch": ["index.js"], "match": "path", "owner": "expressjs", "repo": "express" }
+
+// 4. Read implementation
+{ "owner": "expressjs", "repo": "express", "path": "lib/express.js", "matchString": "createApplication" }
+```
+
+---
+
+### 7. Implementation Tracing (Remote)
+
+**Goal**: Understand how a feature is implemented in an external library.
+
+**Pattern**: Trace from *User Surface* → *Internal Logic* → *Data Layer*.
+
+```
+githubSearchCode(surface) → githubGetFileContent → trace imports → repeat
+```
+
+**Steps:**
+1. **Surface**: Find the public API/Component (e.g., `useState`)
+2. **Definition**: Read the function definition
+3. **Dependency**: Identify one key internal dependency
+4. **Trace**: Search for that dependency's definition
+5. **Repeat**: Continue until you hit the bottom
+
+```json
+// 1. Find feature surface
+{ "keywordsToSearch": ["useState"], "match": "file", "path": "packages/react", "owner": "facebook", "repo": "react" }
+
+// 2. Read definition (The Gate: Read before assuming)
+{ "owner": "facebook", "repo": "react", "path": "packages/react/src/ReactHooks.js", "matchString": "export function useState" }
+
+// 3. Trace dependency
+{ "keywordsToSearch": ["resolveDispatcher"], "match": "file", "owner": "facebook", "repo": "react" }
+```
+
+---
+
+### 8. Bug Investigation
+
+**Goal**: Find root cause of a bug.
+
+```
+githubSearchCode(error) → githubGetFileContent → githubSearchPullRequests
+```
+
+**Steps:**
+1. **Locate Error**: Find where the error string/code is defined
+2. **Read Context**: Read the condition causing the error
+3. **Blame/History**: Who changed this last and why?
+
+```json
+// 1. Find error source
+{ "keywordsToSearch": ["ENOENT"], "match": "file", "owner": "nodejs", "repo": "node" }
+
+// 2. Read context
+{ "owner": "nodejs", "repo": "node", "path": "lib/fs.js", "matchString": "ENOENT" }
+
+// 3. Check history
+{ "query": "file reader ENOENT", "owner": "nodejs", "repo": "node", "merged": true, "type": "metadata" }
+```
+
+---
+
+## Cross-Domain Patterns
+
+### 9. Local → GitHub (Upstream Research)
+
+**Use when**: Local code uses a dependency, need canonical source.
+
+```
+localSearchCode → packageSearch → githubViewRepoStructure → githubGetFileContent
+```
+
+```json
+// 1. Find import in local code
+{ "pattern": "import.*from 'axios'", "path": "src", "filesOnly": true }
+
+// 2. Find package repo
+{ "name": "axios", "ecosystem": "npm" }
+
+// 3. Explore upstream
+{ "owner": "axios", "repo": "axios", "branch": "v1.x", "depth": 1 }
+
+// 4. Read canonical implementation
+{ "owner": "axios", "repo": "axios", "path": "lib/core/Axios.js", "matchString": "class Axios" }
+```
+
+### 10. GitHub → Local (Impact Analysis)
+
+**Use when**: Found upstream change, check local impact.
+
+```
+githubSearchPullRequests → extract changed patterns → localSearchCode
+```
+
+```json
+// 1. Find breaking change PR
+{ "query": "breaking change v2", "owner": "some-lib", "repo": "lib", "merged": true }
+
+// 2. Get changed API (from PR)
+// → Extracted: "oldMethod renamed to newMethod"
+
+// 3. Check local usage
+{ "pattern": "oldMethod", "path": "src", "filesOnly": true }
+```
+
+---
+
+## The Verification Gate
+
+**BEFORE claiming a finding, pass this gate:**
+
+1. **IDENTIFY**: What exact lines of code prove this?
+2. **FETCH**: Did you read the *actual file content*? (Search snippets don't count)
+3. **VERIFY**: Does the logic actually do what you think?
+4. **CHECK DATES**: Is this code from 5 years ago?
+5. **ONLY THEN**: Output the finding.
+
+---
+
+## Batch Queries
+
+Parallelize independent searches (max 3 GitHub, max 5 local):
+
+```json
+{
+  "queries": [
+    { "pattern": "AuthService", "path": "src", "filesOnly": true },
+    { "pattern": "authMiddleware", "path": "src", "filesOnly": true },
+    { "pattern": "AuthUser", "path": "src", "filesOnly": true }
+  ]
+}
+```
+
+---
+
+## Anti-Patterns
+
+| Bad | Good |
+|-----|------|
+| **Citing Search Results** | **Citing File Content** (Read the file!) |
+| **"I assume..."** | **"The code shows..."** |
+| **"Should work like..."** | **"Logic implements..."** |
+| **Broad Search (`auth`)** | **Targeted Search (`class AuthService`)** |
+| **Ignoring Dates** | **Checking `lastModified`** |
+| **Shell commands for search** | **Local tools with pagination** |
+| **Full file dumps** | **matchString + context** |
+
+---
+
+## Checklist
+
+- [ ] **Goal defined?** (Atomic question)
+- [ ] **Local-first?** (Checked workspace before GitHub)
+- [ ] **Code evidence found?** (Line numbers/paths)
+- [ ] **The Gate passed?** (Read full content)
+- [ ] **Cross-referenced?** (Imports/Usage)
+- [ ] **Updated dates checked?**
+- [ ] **Gaps documented?**