opencodekit 0.9.2 → 0.11.0

package/dist/template/.opencode/command/research.md

@@ -1,27 +1,45 @@
 ---
 description: Research a bead - parallel exploration, gather context, save findings
-argument-hint: "<bead-id> [focus area]"
+argument-hint: "<bead-id> [--quick|--thorough] [focus area]"
 agent: build
 ---
 
 # Research
 
+## Depth Levels
+
+| Level        | Tool Calls | Use Case                              |
+| ------------ | ---------- | ------------------------------------- |
+| `--quick`    | ~10        | Single question, API syntax lookup    |
+| (default)    | ~30        | Moderate exploration, verify patterns |
+| `--thorough` | ~100+      | Comprehensive analysis, new domain    |
+
 ## Phase 1: Load Bead Context
 
 ```typescript
 bd_show({ id: "$ARGUMENTS" });
 ```
 
+Reserve research file:
+
+```typescript
+bd_reserve({
+  paths: [".beads/artifacts/<bead-id>/research.md"],
+  reason: "Researching $ARGUMENTS",
+  ttl: 1200,
+});
+```
+
 **Check for previous research:**
 
-```bash
-list_sessions(project="current", since="this week", limit=5)
+```typescript
+list_sessions({ project: "current", since: "this week", limit: 5 });
 ```
 
 If relevant session exists:
 
-```bash
-read_session("<session-id>", focus="research")
+```typescript
+read_session({ session_reference: "<session-id>", focus: "research" });
 ```
 
 Review existing findings before duplicating work.
@@ -37,47 +55,112 @@ Extract:
 - **Problem statement** - What we're solving
 - **Requirements** - What must be done
 - **Scope** - In/out boundaries
-- **Open Questions** - What needs investigation
+- **Open Questions** - What needs investigation (prioritize by importance)
 
 ## Phase 2: Parallel Exploration
 
-Run these **in parallel** using batch tool calls:
+Run these **in parallel** using batch tool calls.
+
+### Source Quality Tiers
+
+Prioritize sources in this order:
 
-### Internal Codebase
+| Tier | Source                 | Trust Level | When to Use                 |
+| ---- | ---------------------- | ----------- | --------------------------- |
+| 1    | Codebase patterns      | Highest     | Always check first          |
+| 1    | Official documentation | Highest     | Authoritative answers       |
+| 2    | Context7 library docs  | High        | API usage, examples         |
+| 2    | GitHub code examples   | High        | Real-world patterns         |
+| 3    | Blog posts, tutorials  | Medium      | Concepts, approaches        |
+| 3    | Stack Overflow         | Medium      | Troubleshooting, edge cases |
 
-- `grep` - Find related functions/classes by pattern
-- `ast-grep` - Semantic code search for patterns
-- `glob` - Map relevant directories
+### Internal Codebase (Tier 1)
 
-### External Docs (Context7)
+```typescript
+// Semantic understanding
+lsp_find_references({ filePath: "<file>", line: N, character: N });
+lsp_hover({ filePath: "<file>", line: N, character: N });
+lsp_document_symbols({ filePath: "<file>" });
+
+// Pattern search
+ast-grep({ pattern: "<code pattern>" });
+grep({ pattern: "<text pattern>", include: "*.ts" });
+glob({ pattern: "**/*<name>*" });
+
+// History for "why" questions
+git log -p --follow -S "<search term>" -- <file>
+git blame <file> | grep "<pattern>"
+```
+
+### External Docs - Context7 (Tier 2)
+
+Only for libraries in spec's allowed list:
+
+```typescript
+context7_resolve - library - id({ libraryName: "<lib>", query: "<question>" });
+context7_query -
+  docs({ libraryId: "<resolved-id>", query: "<specific question>" });
+```
+
+### Code Examples - codesearch/gh_grep (Tier 2)
+
+Real-world patterns from GitHub:
 
-- Only for libraries in spec's allowed list
-- `context7_resolve-library-id` → `context7_get-library-docs`
+```typescript
+codesearch({ query: "<API usage pattern>", tokensNum: 5000 });
+gh_grep_searchGitHub({ query: "<code pattern>", language: ["TypeScript"] });
+```
 
-### Code Examples (codesearch)
+Use actual code patterns, not keywords.
 
-- Real-world patterns from GitHub
-- Use regex patterns, not keywords
+### Web Research - websearch (Tier 3)
 
-### Web Research (websearch)
+Only if Tier 1-2 don't answer the question:
 
-- Documentation, articles, best practices
-- Only if Context7 doesn't have it
+```typescript
+websearch({ query: "<specific question>", numResults: 5 });
+```
 
 ## Phase 3: Filter & Validate
 
-For each finding:
+For each finding, assess:
+
+### Validation Checklist
+
+- [ ] Within spec scope?
+- [ ] Follows constraints?
+- [ ] Uses allowed libs?
+- [ ] Matches existing codebase patterns?
+
+### Confidence Scoring
+
+| Confidence | Criteria                                              |
+| ---------- | ----------------------------------------------------- |
+| **High**   | Multiple Tier 1-2 sources agree, verified in codebase |
+| **Medium** | Single authoritative source, plausible but unverified |
+| **Low**    | Tier 3 sources only, conflicting info, speculation    |
+
+### Contradiction Handling
 
-**Validation checklist:**
+When sources disagree:
 
-- Within spec scope?
-- Follows constraints?
-- Uses allowed libs?
-- Matches existing patterns?
+1. Prefer Tier 1 over Tier 2 over Tier 3
+2. Prefer more recent sources
+3. Prefer sources matching your tech stack version
+4. Document the contradiction and both perspectives
 
-**Discard anything that fails.**
+**Discard findings that fail validation or have Low confidence without corroboration.**
 
-## Phase 4: Document Findings
+## Phase 4: Stopping Criteria
+
+Stop research when ANY of these are true:
+
+- [ ] All spec questions answered with Medium+ confidence
+- [ ] Tool call budget exhausted (quick: 10, default: 30, thorough: 100)
+- [ ] Diminishing returns: last 5 tool calls yielded no new insights
+- [ ] Blocked: need human input to proceed
+
+## Phase 5: Document Findings
 
 Write to `.beads/artifacts/<bead-id>/research.md`:
 
@@ -86,51 +169,88 @@ Write to `.beads/artifacts/<bead-id>/research.md`:
 
 **Bead:** <bead-id>
 **Date:** <date>
-**Spec:** .beads/artifacts/<bead-id>/spec.md
+**Depth:** [quick|medium|thorough]
+**Tool calls:** [N]
 
 ## Questions Investigated
 
-1. [Question from spec]
-2. [Question from spec]
+1. [Question from spec] → **Answered** (High confidence)
+2. [Question from spec] → **Partial** (Medium confidence)
+3. [Question from spec] → **Unanswered** (needs more info)
 
 ## Findings
 
 ### [Topic 1]
 
-**Source:** [file:line | URL | library docs]
+**Confidence:** High
+**Sources:**
+
+- Tier 1: `src/utils/auth.ts:42` - existing pattern
+- Tier 2: Context7 /vercel/next.js - official docs
+
+**Finding:** [Key insight with code example]
+
+**Basis for confidence:** Multiple authoritative sources agree, pattern exists in codebase.
 
-[Key insight with code example if applicable]
+---
 
 ### [Topic 2]
 
-**Source:** [file:line | URL | library docs]
+**Confidence:** Medium
+**Sources:**
+
+- Tier 2: codesearch - GitHub examples
+
+**Finding:** [Key insight]
 
-[Key insight]
+**Basis for confidence:** Single source, but from reputable repo.
+
+**Contradiction note:** [If applicable - what sources disagreed and why we chose this interpretation]
+
+---
 
 ## Codebase Patterns
 
 Existing code that informs implementation:
 
-- `src/utils/foo.ts:42` - [pattern description]
-- `src/components/Bar.tsx:15-30` - [pattern description]
+| Location                 | Pattern   | Relevance |
+| ------------------------ | --------- | --------- |
+| `src/utils/foo.ts:42`    | [pattern] | Direct    |
+| `src/components/Bar.tsx` | [pattern] | Similar   |
 
 ## Constraints Discovered
 
-- [Constraint 1] - [reason]
-- [Constraint 2] - [reason]
+- [Constraint 1] - [reason] (Confidence: High)
+- [Constraint 2] - [reason] (Confidence: Medium)
 
 ## Recommendation
 
-[Recommended approach based on findings]
+**Approach:** [Recommended approach based on findings]
+
+**Confidence:** [High/Medium/Low]
+
+**Rationale:** [Why this approach, citing findings]
 
 ## Open Items
 
-- [ ] [Remaining uncertainty]
+- [ ] [Remaining uncertainty] - needs: [what would resolve it]
+- [ ] [Blocked question] - needs: [human input / more context]
 ```
 
-## Phase 5: Update Bead
+## Phase 6: Update Bead & Sync
 
-Add a note about research completion via `bd_msg` or update the spec with key findings.
+```typescript
+bd_msg({
+  subj: "Research complete",
+  body: "Findings: [count]\nConfidence: [overall]\nOpen items: [count]",
+  to: "all",
+  importance: "normal",
+  global: false,
+});
+
+bd_release({ _: true });
+bd_sync({ reason: "Research complete for $ARGUMENTS" });
+```
 
 ## Output
 
@@ -138,14 +258,22 @@ Add a note about research completion via `bd_msg` or update the spec with key fi
 Research Complete: <bead-id>
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+Depth: [quick|medium|thorough]
+Tool calls: [N]
 Findings saved: .beads/artifacts/<bead-id>/research.md
 
+Questions:
+• [question 1] → Answered (High)
+• [question 2] → Partial (Medium)
+
 Key Insights:
-• [insight 1]
-• [insight 2]
+• [insight 1] (High confidence)
+• [insight 2] (Medium confidence)
 
 Constraints:
 • [constraint 1]
 
+Open Items: [N] remaining
+
 Next: /plan <bead-id>
 ```