opencodekit 0.12.2 → 0.12.4

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

@@ -1,289 +1,164 @@
 ---
-description: Research a bead - parallel exploration, gather context, save findings
-argument-hint: "<bead-id> [--quick|--thorough] [focus area]"
-agent: build
+description: Research a topic or bead before implementation
+argument-hint: "<bead-id> [--quick|--thorough]"
+agent: scout
 ---
 
-# Research
+# Research: $ARGUMENTS
 
-## Load Beads Skill
-
-```typescript
-skill({ name: "beads" });
-```
+You're gathering information before implementation. Find answers, document findings, stop when done.
 
 ## 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    |
+- `--quick` (~10 tool calls): Single question, API syntax lookup
+- Default (~30 tool calls): Moderate exploration, verify patterns
+- `--thorough` (~100+ tool calls): Comprehensive analysis, new domain
 
-## Phase 1: Load Bead Context
+## Load Context
 
-```typescript
-bd_show({ id: "$ARGUMENTS" });
+```bash
+bd show $ARGUMENTS
+cat .beads/artifacts/$ARGUMENTS/spec.md
 ```
 
-Reserve research file:
-
-```typescript
-bd_reserve({
-  paths: [".beads/artifacts/<bead-id>/research.md"],
-  reason: "Researching $ARGUMENTS",
-  ttl: 1200,
-});
-```
+Extract the questions that need answering from the spec.
 
-**Check for previous research:**
+## Check For Previous Research
 
 ```typescript
-// Search for past research on this topic
-search_session({ query: "<topic keywords>" });
-
-// Also check recent sessions
+search_session({ query: "[topic keywords]" });
 list_sessions({ project: "current", since: "this week", limit: 5 });
 ```
 
-If relevant session exists:
+Don't duplicate work that's already been done.
 
-```typescript
-read_session({ session_reference: "<session-id>", focus: "research" });
-```
+## Source Priority
 
-Review existing findings before duplicating work.
+1. **Codebase patterns** (highest trust) - How does this project already do it?
+2. **Official docs** (high trust) - What does the library documentation say?
+3. **Context7** (high trust) - API usage and examples
+4. **GitHub examples** (medium trust) - Real-world patterns via codesearch/gh_grep
+5. **Web search** (lower trust) - Only if tiers 1-4 don't answer
 
-Read spec for boundaries:
-
-```bash
-cat .beads/artifacts/<bead-id>/spec.md
-```
+## Research
 
-Extract:
-
-- **Problem statement** - What we're solving
-- **Requirements** - What must be done
-- **Scope** - In/out boundaries
-- **Open Questions** - What needs investigation (prioritize by importance)
-
-## Phase 2: Parallel Exploration
-
-Run these **in parallel** using batch tool calls.
-
-### Source Quality Tiers
-
-Prioritize sources in this order:
-
-| 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 |
-
-### Internal Codebase (Tier 1)
+### Internal Codebase
 
 ```typescript
-// Semantic understanding
-lsp_lsp_find_references({ filePath: "<file>", line: N, character: N });
-lsp_lsp_hover({ filePath: "<file>", line: N, character: N });
-lsp_lsp_document_symbols({ filePath: "<file>" });
-
-// Pattern search
-ast-grep({ pattern: "<code pattern>" });
+// Find similar patterns
+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>"
+// Understand types
+lsp_lsp_hover({ filePath: "<file>", line: N, character: N });
+lsp_lsp_find_references({ filePath: "<file>", line: N, character: N });
 ```
 
-### External Docs - Context7 (Tier 2)
-
-Only for libraries in spec's allowed list:
+### External Docs
 
 ```typescript
-context7_resolve - library - id({ libraryName: "<lib>", query: "<question>" });
-context7_query -
-  docs({ libraryId: "<resolved-id>", query: "<specific question>" });
+context7_resolve_library_id({ libraryName: "<lib>", query: "<question>" });
+context7_query_docs({ libraryId: "<id>", query: "<specific question>" });
 ```
 
-### Code Examples - codesearch/gh_grep (Tier 2)
-
-Real-world patterns from GitHub:
+### Code Examples
 
 ```typescript
 codesearch({ query: "<API usage pattern>", tokensNum: 5000 });
 gh_grep_searchGitHub({ query: "<code pattern>", language: ["TypeScript"] });
 ```
 
-Use actual code patterns, not keywords.
-
-### Web Research - websearch (Tier 3)
-
-Only if Tier 1-2 don't answer the question:
-
-```typescript
-websearch({ query: "<specific question>", numResults: 5 });
-```
-
-## Phase 3: Filter & Validate
+## Validate Findings
 
-For each finding, assess:
+For each finding:
 
-### Validation Checklist
+- Within spec scope?
+- Follows project constraints?
+- Uses allowed libs?
+- Matches existing codebase patterns?
 
-- [ ] Within spec scope?
-- [ ] Follows constraints?
-- [ ] Uses allowed libs?
-- [ ] Matches existing codebase patterns?
+**Confidence levels:**
 
-### Confidence Scoring
+- **High**: Multiple authoritative sources agree, verified in codebase
+- **Medium**: Single good source, plausible but unverified
+- **Low**: Conflicting info, speculation
 
-| 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    |
+Discard low-confidence findings without corroboration.
 
-### Contradiction Handling
+## Stop When
 
-When sources disagree:
+- All spec questions answered with medium+ confidence
+- Tool budget exhausted
+- Last 5 tool calls yielded no new insights
+- Blocked and need human input
 
-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
+## Document Findings
 
-**Discard findings that fail validation or have Low confidence without corroboration.**
-
-## 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`:
+Write `.beads/artifacts/$ARGUMENTS/research.md`:
 
 ```markdown
 # Research: [Title]
 
-**Bead:** <bead-id>
-**Date:** <date>
+**Bead:** $ARGUMENTS
 **Depth:** [quick|medium|thorough]
 **Tool calls:** [N]
 
-## Questions Investigated
+## Questions
 
-1. [Question from spec] → **Answered** (High confidence)
-2. [Question from spec] → **Partial** (Medium confidence)
-3. [Question from spec] → **Unanswered** (needs more info)
+1. [Question] → Answered (High)
+2. [Question] → Partial (Medium)
+3. [Question] → Unanswered
 
-## Findings
+## Key Findings
 
 ### [Topic 1]
 
 **Confidence:** High
-**Sources:**
-
-- Tier 1: `src/utils/auth.ts:42` - existing pattern
-- Tier 2: Context7 /vercel/next.js - official docs
+**Sources:** `src/utils/auth.ts:42`, Context7 /vercel/next.js
 
-**Finding:** [Key insight with code example]
-
-**Basis for confidence:** Multiple authoritative sources agree, pattern exists in codebase.
+[Finding with code example]
 
 ---
 
 ### [Topic 2]
 
 **Confidence:** Medium
-**Sources:**
-
-- Tier 2: codesearch - GitHub examples
-
-**Finding:** [Key insight]
-
-**Basis for confidence:** Single source, but from reputable repo.
-
-**Contradiction note:** [If applicable - what sources disagreed and why we chose this interpretation]
+[Finding]
 
 ---
 
-## Codebase Patterns
-
-Existing code that informs implementation:
-
-| Location                 | Pattern   | Relevance |
-| ------------------------ | --------- | --------- |
-| `src/utils/foo.ts:42`    | [pattern] | Direct    |
-| `src/components/Bar.tsx` | [pattern] | Similar   |
-
-## Constraints Discovered
-
-- [Constraint 1] - [reason] (Confidence: High)
-- [Constraint 2] - [reason] (Confidence: Medium)
-
 ## Recommendation
 
-**Approach:** [Recommended approach based on findings]
-
-**Confidence:** [High/Medium/Low]
-
-**Rationale:** [Why this approach, citing findings]
+[Approach based on findings]
 
 ## Open Items
 
-- [ ] [Remaining uncertainty] - needs: [what would resolve it]
-- [ ] [Blocked question] - needs: [human input / more context]
+- [Remaining question] - needs: [what would resolve it]
 ```
 
-## Phase 6: Update Bead & Sync
+## Sync
 
 ```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" });
+bd_sync({ reason: "Sync research findings" });
 ```
 
 ## Output
 
 ```
-Research Complete: <bead-id>
-━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Research: $ARGUMENTS
 
 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] (High confidence)
-• [insight 2] (Medium confidence)
+• [Q1] → Answered (High)
+• [Q2] → Partial (Medium)
 
-Constraints:
-• [constraint 1]
+Key insights:
+• [insight 1]
+• [insight 2]
 
-Open Items: [N] remaining
+Open items: [N]
 
-Next: /plan <bead-id>
+Next: /plan $ARGUMENTS
 ```