# Plan: Optimize Scout Agent for External Research

**Goal:** Enhance Scout agent prompt with missing tool integrations and workflows for optimal external research.

**Scope:** READ-ONLY external research only (no local codebase changes)

---

## Changes Required

### File: `.opencode/agent/scout.md`

#### 1. Add Memory-First Protocol (after line 43, before "External research:")

````markdown
## Memory First

Before hitting external APIs, check past research:

```typescript
memory - search({ query: "<topic keywords>", limit: 3 });
```
````

If memory returns high-confidence findings on this exact topic, synthesize and return without external calls. Only proceed to external sources if:

- No relevant memory found
- Memory findings are outdated or low-confidence
- Question requires fresher data

````

#### 2. Add Tool Priority Section (replace/enhance "## Guidelines" around line 88)

```markdown
## Tool Priority (External Sources Only)

| Priority | Tool | Use Case | Speed |
|----------|------|----------|-------|
| 1 | memory-search | Past research findings | Instant |
| Priority | Tool | Use Case | Speed |
|----------|------|----------|-------|
| 1 | memory-search | Past research findings | Instant |
| 2 | context7_resolve-library-id | Resolve library names to IDs | Fast |
| 3 | context7_query-docs | Official library docs | Fast |
| 4 | codesearch | Exa Code API for SDK/library patterns | Fast |
| 5 | grepsearch | Cross-repo GitHub code search | Medium |
| 6 | webfetch | Specific doc URLs, READMEs, changelogs | Medium |
| 7 | opensrc + LSP | Clone & analyze source code | Slow |
| 8 | websearch | Tutorials, blog posts, recent news | Slow |
| 3 | codesearch | Usage patterns in real code | Fast |
| 4 | gh_grep | Cross-repo deep code search | Medium |
| 5 | webfetch | Specific doc URLs, READMEs, changelogs | Medium |
| 6 | opensrc + LSP | Clone & analyze source code | Slow |
| 7 | websearch | Tutorials, blog posts, recent news | Slow |

**Rule:** Exhaust faster tools before slower ones. Run tools in parallel when independent.
````

#### 3. Add webfetch Section (new section after Tool Priority)

````markdown
## webfetch Usage

Use `webfetch` for specific external URLs when you have a known target:

```typescript
// GitHub raw files
webfetch({
  url: "https://raw.githubusercontent.com/owner/repo/main/README.md",
  format: "markdown",
});

// Documentation pages
webfetch({ url: "https://zod.dev/docs/guides/async", format: "markdown" });

// Release notes
webfetch({ url: "https://github.com/colinhacks/zod/releases", format: "markdown" });

// API references
webfetch({ url: "https://docs.example.com/api/authentication", format: "markdown" });
```
````

**When to use:**

- User provides a specific URL
- context7_resolve-library-id returns a library ID
- context7_query-docs returns a doc link worth fetching
- Need CHANGELOG or release notes
- GitHub README has details not in context7

````

#### 4. Add Source Code Deep Dive Section (new section, expand on existing clone guidance)

```markdown
## Source Code Deep Dive

When documentation is insufficient, analyze actual source code.

### Step 1: Load the Skill
```typescript
skill({ name: "source-code-research" })
````

### Step 2: Clone the Package

```bash
npx opensrc <package>           # npm (auto-detects version)
npx opensrc <package>@<version> # specific version
npx opensrc pypi:<package>      # Python
npx opensrc <owner>/<repo>      # GitHub repo
```

### Step 3: Navigate with LSP

After cloning, source lands in `opensrc/repos/github.com/<owner>/<repo>/`. Use LSP:

```typescript
// Get file structure
lsp({
  operation: "documentSymbol",
  filePath: "opensrc/repos/.../src/index.ts",
  line: 1,
  character: 1,
});

// Jump to definition
lsp({
  operation: "goToDefinition",
  filePath: "opensrc/repos/.../src/types.ts",
  line: 42,
  character: 10,
});

// Find all usages
lsp({
  operation: "findReferences",
  filePath: "opensrc/repos/.../src/core.ts",
  line: 100,
  character: 5,
});
```

### Step 4: Search Within Clone

```typescript
// Find specific patterns
grep({ pattern: "async.*refine", path: "opensrc/", include: "*.ts" });

// Check tests for usage examples
glob({ pattern: "opensrc/**/test/**/*.ts" });
glob({ pattern: "opensrc/**/*.test.ts" });
```

### Step 5: Construct Permalinks

Build GitHub permalinks from cloned code:

```
https://github.com/<owner>/<repo>/blob/<sha>/path/to/file.ts#L42-L56
```

Get SHA from `opensrc/sources.json` or the cloned repo.

````

#### 5. Update Fallback Chain in "When Things Fail" Section (enhance existing)

```markdown
## When Things Fail

### Fallback Chain
````

context7 fails → try codesearch for patterns
codesearch empty → try gh_grep with broader query
gh_grep empty → webfetch specific doc URLs if known
still stuck → opensrc clone + LSP analysis
last resort → websearch for tutorials/blogs

```

### Specific Failures

**context7 doesn't find library:**
1. Try `codesearch({ query: "<library> <function> example" })`
2. Try `gh_grepsearchGitHub({ query: "import.*from.*<library>" })`
3. Clone with `npx opensrc <library>` and read source

**gh_grep returns nothing:**
- Broaden query: search concepts, not exact function names
- Try different language filters
- Search for error messages or config patterns

**opensrc clone fails:**
- Check if package exists on npm/pypi/crates
- Try GitHub URL directly: `npx opensrc owner/repo`
- Fall back to `webfetch` on raw GitHub files

**API rate limits:**
- Work from already-cloned repos in `opensrc/`
- Use `memory-search` to find cached findings
- Reduce parallel calls, go sequential
```

---

## Summary of Additions

| Addition                | Lines | Purpose                                   |
| ----------------------- | ----- | ----------------------------------------- |
| Memory-First Protocol   | ~15   | Check past research before external calls |
| Tool Priority Table     | ~15   | Clear hierarchy for tool selection        |
| webfetch Section        | ~25   | Document missing tool usage               |
| Source Code Deep Dive   | ~50   | Full opensrc + LSP workflow               |
| Enhanced Fallback Chain | ~30   | Clear failure recovery paths              |

**Total additions:** ~135 lines

---

## Files to Modify

1. `.opencode/agent/scout.md` - Add sections above

---

## Verification

After implementation:

1. Test Quick Mode: `@scout how to use zod .refine()`
2. Test Deep Mode: `@scout how do production apps handle zod async validation`
3. Test Source Dive: `@scout show me zod's internal parse implementation`
4. Verify memory check appears in scout's first actions
5. Verify webfetch used when given specific URLs

---

## Out of Scope

- Local codebase access (that's Explore agent)
- File modifications outside `.beads/artifacts/`
- Question tool (subagent constraint)
- New MCP integrations (uses existing tools)
