octocode-cli 1.1.1 → 1.2.0

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

@@ -0,0 +1,385 @@
+# Workflow Patterns - Implementation Agent
+
+Common implementation flows for different task types.
+
+---
+
+## Pre-Implementation Patterns
+
+### 1. Codebase Orientation (First Time)
+
+**Use when**: New to the repository, need mental model.
+
+```
+localViewStructure(root, depth=1) → identify src/tests/config → drill into src (depth=2)
+```
+
+**Steps:**
+1. **Map Root**: See top-level structure
+2. **Identify Key Dirs**: src, tests, config, types
+3. **Drill Into Source**: Understand feature organization
+4. **Find Entry Points**: main.ts, index.ts, app.ts
+5. **Note Test Structure**: How are tests organized?
+
+```json
+// 1. Map root
+{ "path": "", "depth": 1 }
+
+// 2. Drill into source
+{ "path": "src", "depth": 2 }
+
+// 3. Find entry points
+{ "pattern": "createApp|bootstrap|main", "path": "src", "filesOnly": true }
+
+// 4. Understand test structure
+{ "path": "tests", "depth": 1 }
+```
+
+**Output**: Clear mental model of where things live.
+
+---
+
+### 2. Feature Area Discovery
+
+**Use when**: Know what feature to implement, need to find where.
+
+```
+localSearchCode(featureName, filesOnly) → localGetFileContent → trace dependencies
+```
+
+**Steps:**
+1. **Search for Similar**: Find existing similar features
+2. **Read Implementation**: Understand the pattern
+3. **Trace Dependencies**: What does it import/use?
+4. **Find Tests**: How is it tested?
+
+```json
+// 1. Find similar feature
+{ "pattern": "export.*UserService|class.*UserService", "path": "src", "filesOnly": true }
+
+// 2. Read implementation
+{ "path": "src/services/UserService.ts", "matchString": "export class UserService", "matchStringContextLines": 50 }
+
+// 3. Find tests
+{ "pattern": "describe.*UserService", "path": "tests", "filesOnly": true }
+```
+
+---
+
+### 3. Impact Analysis (Before Modification)
+
+**Use when**: About to modify existing code, need to understand impact.
+
+```
+lspFindReferences → lspCallHierarchy(incoming) → map affected files
+```
+
+**Steps:**
+1. **Find All Usages**: Who uses this function/class?
+2. **Trace Callers**: What's the call chain?
+3. **Map Affected Files**: Create change impact list
+4. **Prioritize**: Which callers need updates?
+
+```json
+// 1. Find all usages
+{ "uri": "src/core/processor.ts", "symbolName": "processData", "lineHint": 45, "includeDeclaration": false }
+
+// 2. Trace call hierarchy
+{ "uri": "src/core/processor.ts", "symbolName": "processData", "lineHint": 45, "direction": "incoming", "depth": 2 }
+```
+
+**Output**: List of files that need attention.
+
+---
+
+## Implementation Patterns
+
+### 4. Feature Addition (Copy Pattern)
+
+**Use when**: Adding new feature similar to existing one.
+
+```
+Find Similar → Read Thoroughly → Copy Structure → Adapt → Test
+```
+
+**Steps:**
+1. **Find Exemplar**: Locate similar existing feature
+2. **Deep Read**: Read entire implementation + tests
+3. **Copy Structure**: Create files mirroring the pattern
+4. **Adapt Content**: Modify for new requirements
+5. **Add Tests**: Follow same test patterns
+6. **Validate**: Run test suite
+
+```json
+// 1. Find similar feature
+{ "pattern": "export class ProductService", "path": "src/services", "filesOnly": true }
+
+// 2. Read implementation fully
+{ "path": "src/services/ProductService.ts", "fullContent": true }  // if small
+// OR
+{ "path": "src/services/ProductService.ts", "matchString": "export class", "matchStringContextLines": 100 }
+
+// 3. Read its tests
+{ "path": "tests/services/ProductService.test.ts", "fullContent": true }
+
+// 4. Create new files following same patterns...
+```
+
+---
+
+### 5. API Addition
+
+**Use when**: Adding new endpoint/method to existing API.
+
+```
+Find API Layer → Read Existing Endpoints → Copy Pattern → Add Types → Test
+```
+
+**Steps:**
+1. **Locate API Layer**: Find route/controller files
+2. **Read Existing**: Understand endpoint patterns
+3. **Find Types**: Locate request/response types
+4. **Find Validation**: How is input validated?
+5. **Implement**: Follow exact pattern
+6. **Add Tests**: Follow API test patterns
+
+```json
+// 1. Find API routes
+{ "pattern": "@(Controller|Router|Get|Post)", "path": "src", "type": "ts", "filesOnly": true }
+
+// 2. Read existing endpoint
+{ "path": "src/api/users.ts", "matchString": "@Get", "matchStringContextLines": 30 }
+
+// 3. Find types
+{ "pattern": "interface.*Request|interface.*Response", "path": "src/types", "filesOnly": true }
+
+// 4. Find validation
+{ "pattern": "validate|schema|zod|yup", "path": "src/api", "filesOnly": true }
+```
+
+---
+
+### 6. Bug Fix
+
+**Use when**: Fixing specific broken behavior.
+
+```
+Understand Bug → Locate Code → Trace Flow → Find Root Cause → Minimal Fix → Regression Test
+```
+
+**Steps:**
+1. **Understand**: What's expected vs actual?
+2. **Locate**: Find the relevant code area
+3. **Trace Flow**: How does data flow through?
+4. **Root Cause**: Why does it fail?
+5. **Minimal Fix**: Change as little as possible
+6. **Test**: Add regression test
+
+```json
+// 1. Find relevant area
+{ "pattern": "handleUserLogin|processLogin", "path": "src", "filesOnly": true }
+
+// 2. Read implementation
+{ "path": "src/auth/login.ts", "matchString": "handleUserLogin", "matchStringContextLines": 40 }
+
+// 3. Trace the flow
+{ "uri": "src/auth/login.ts", "symbolName": "handleUserLogin", "lineHint": 25, "direction": "outgoing" }
+
+// 4. Find where validation happens
+{ "pattern": "validate.*credentials|checkPassword", "path": "src/auth" }
+```
+
+---
+
+### 7. Refactoring (Rename/Move)
+
+**Use when**: Restructuring without changing behavior.
+
+```
+Find ALL References → Plan Changes → Execute Incrementally → Keep Tests Green
+```
+
+**CRITICAL**: Tests must pass after EVERY change.
+
+**Steps:**
+1. **Find All Usages**: Complete impact analysis
+2. **Plan Order**: Determine safe change order
+3. **Execute One**: Make single atomic change
+4. **Run Tests**: Must pass
+5. **Repeat**: Continue until complete
+
+```json
+// 1. Find ALL references
+{ "uri": "src/utils/helper.ts", "symbolName": "oldFunctionName", "lineHint": 10, "includeDeclaration": true }
+
+// 2. Use LSP across all found files
+// ... then make changes file by file, testing after each
+```
+
+---
+
+### 8. Interface Change
+
+**Use when**: Modifying types/interfaces used by multiple modules.
+
+```
+Find All Usages → Assess Impact → Update Types → Update Consumers → Update Implementation
+```
+
+**Steps:**
+1. **Find All Usages**: Where is this type used?
+2. **Categorize**: Type assertions, function params, returns
+3. **Plan Migration**: Adding required field? Make optional first
+4. **Update Types**: Change the interface
+5. **Update Consumers**: Fix each usage
+6. **Validate**: Full test suite
+
+```json
+// 1. Find type usages
+{ "uri": "src/types/user.ts", "symbolName": "UserDTO", "lineHint": 5, "includeDeclaration": true, "referencesPerPage": 50 }
+
+// 2. Categorize by reviewing each reference
+// 3. Make changes incrementally
+```
+
+---
+
+### 9. Adding Tests
+
+**Use when**: Need to add tests for existing code.
+
+```
+Find Code → Understand Behavior → Find Test Patterns → Write Tests
+```
+
+**Steps:**
+1. **Read Code**: Understand what to test
+2. **Find Test Patterns**: How are similar things tested?
+3. **Find Mocking Patterns**: How are dependencies mocked?
+4. **Write Tests**: Follow existing patterns
+5. **Run**: Ensure they pass
+
+```json
+// 1. Read the code to test
+{ "path": "src/services/OrderService.ts", "matchString": "export class OrderService", "matchStringContextLines": 100 }
+
+// 2. Find similar test patterns
+{ "pattern": "describe.*Service", "path": "tests", "filesOnly": true }
+
+// 3. Read a similar test file
+{ "path": "tests/services/UserService.test.ts", "fullContent": true }
+
+// 4. Find mocking patterns
+{ "pattern": "mock|jest.fn|vi.fn|beforeEach", "path": "tests/services/UserService.test.ts" }
+```
+
+---
+
+## Advanced Patterns
+
+### 10. Cross-Module Feature
+
+**Use when**: Feature spans multiple modules/packages.
+
+```
+Map All Affected Modules → Research Each → Plan Integration Order → Implement Bottom-Up
+```
+
+**Steps:**
+1. **Map Scope**: Which modules are affected?
+2. **Research Each**: Understand each module's patterns
+3. **Find Integration Points**: How do they communicate?
+4. **Plan Order**: Bottom-up (dependencies first)
+5. **Implement**: One module at a time, test between
+
+---
+
+### 11. External Library Integration
+
+**Use when**: Integrating a new third-party library.
+
+```
+packageSearch → Read Upstream Docs → Find Local Examples → Implement Wrapper → Test
+```
+
+**Steps:**
+1. **Find Library**: `packageSearch` for repo location
+2. **Read Docs**: Understand API from upstream
+3. **Find Local Examples**: Are similar libs used locally?
+4. **Plan Wrapper**: How to isolate the dependency
+5. **Implement**: Follow local patterns for external deps
+6. **Test**: Include integration tests
+
+```json
+// 1. Find library repo
+{ "name": "axios", "ecosystem": "npm" }
+
+// 2. Search for existing usage patterns locally
+{ "pattern": "import.*from 'axios'|require.*axios", "path": "src", "filesOnly": true }
+
+// 3. Read existing wrapper if any
+{ "path": "src/utils/http.ts", "matchString": "axios", "matchStringContextLines": 30 }
+```
+
+---
+
+### 12. Performance Optimization
+
+**Use when**: Need to improve performance of existing code.
+
+```
+Profile/Identify → Understand Current Flow → Find Optimization Patterns → Apply → Measure
+```
+
+**Steps:**
+1. **Identify**: What's slow? (from spec)
+2. **Trace Flow**: Understand current implementation
+3. **Find Patterns**: How are similar things optimized in codebase?
+4. **Research**: Check for caching, batching, async patterns
+5. **Apply**: Make targeted changes
+6. **Validate**: Ensure correctness, measure improvement
+
+```json
+// 1. Read slow code
+{ "path": "src/data/processor.ts", "matchString": "processLargeDataset", "matchStringContextLines": 50 }
+
+// 2. Trace its calls
+{ "uri": "src/data/processor.ts", "symbolName": "processLargeDataset", "lineHint": 30, "direction": "outgoing", "depth": 2 }
+
+// 3. Find optimization patterns in codebase
+{ "pattern": "cache|memo|batch|Promise\\.all|concurrent", "path": "src", "filesOnly": true }
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+| Bad | Good |
+|-----|------|
+| **Implementing without reading similar code** | **Find exemplar first, then copy pattern** |
+| **Modifying without impact analysis** | **lspFindReferences before any change** |
+| **Writing new patterns** | **Follow existing codebase patterns** |
+| **Big bang changes** | **Small incremental changes with tests** |
+| **Skipping tests** | **Tests for every change** |
+| **Guessing file locations** | **Search first, then read** |
+| **Reading entire files** | **Use matchString for targeted reads** |
+
+---
+
+## Checklist Before Starting Implementation
+
+- [ ] **Spec understood?** (Requirements clear)
+- [ ] **Codebase mapped?** (Know where things are)
+- [ ] **Similar feature found?** (Pattern to follow)
+- [ ] **Impact analyzed?** (Know what's affected)
+- [ ] **Test patterns found?** (Know how to test)
+- [ ] **User checkpoint?** (Approach confirmed)
+
+## Checklist Before Declaring Done
+
+- [ ] **All tasks complete?** (Per TodoWrite)
+- [ ] **Patterns followed?** (No new patterns)
+- [ ] **Tests added?** (Coverage maintained)
+- [ ] **Validation passed?** (Compile, lint, test)
+- [ ] **No scope creep?** (Only what spec asked)
+