External Research Skill

Guidelines for when and how agents should research external sources during planning and problem-solving.

When to Research

Always Research When

• •Working with an unfamiliar API or framework (even if you think you know it)
• •Debugging platform-specific behavior (iOS, watchOS, Electron quirks)
• •Planning a performance optimization (measure first, research approaches)
• •Encountering an error code you can't explain from context alone
• •Implementing security-sensitive features (auth, crypto, input validation)
• •The user explicitly asks for best practices or industry standards

Don't Research When

• •The answer is clearly in the codebase (use grep/search instead)
• •You're implementing a well-known, basic pattern (standard CRUD, simple UI layout)
• •The user has already provided specific instructions to follow
• •You're making a routine edit to existing code that follows established patterns

Gray Area — Research If Unsure

• •You're "pretty sure" about an API behavior but haven't verified
• •The last time you saw this pattern was in a different framework version
• •You're about to write code that handles edge cases you haven't tested

Rule of thumb: If you're about to write a comment like "I think this works because..." — research it first.

Research-First Planning Pattern

flowchart TD
    A[Task Received] --> B{Unknowns?}
    B -->|Yes| C[Identify specific questions]
    B -->|No| G[Plan directly]
    C --> D[Research external sources]
    D --> E[Synthesize findings]
    E --> F[Create plan with citations]
    F --> G
    G --> H[Implement]

Step 1: Identify Unknowns

Before writing any plan, list what you don't know:

• •"How does watchOS handle .task modifier cancellation?"
• •"What's the recommended way to share Keychain items between iPhone and Watch?"
• •"Does rsync --update compare by mtime or content?"

Step 2: Research

Use search_web with specific, technical queries:

• •✅ Good: "watchOS SwiftUI .task modifier cancellation behavior structured concurrency"
• •❌ Bad: "how to fix watch app"

Step 3: Synthesize

Distill findings into actionable context:

• •What the official documentation says
• •What developers report in practice (Stack Overflow, forums)
• •What edge cases exist
• •What the recommended pattern is

Step 4: Cite in Plans

Include research in your implementation plan:

## Research Findings

### watchOS Task Cancellation
**Source:** [Apple Developer Forums](URL) + [watchOS programming guide](URL)
**Finding:** watchOS aggressively cancels `.task` modifier contexts when app enters background.
**Implication:** Must use unstructured `Task {}` for network calls that need to survive app suspension.

Source Quality Hierarchy

Citation Format

In Plans and Docs

**Source:** [Title](URL) — [one-line summary of what it says]

In Code Comments

// watchOS cancels .task contexts during app suspension
// (ref: Apple Developer Forums, URLError -999 in structured concurrency)
Task { await vm.refresh() }

In Collab Files

## Research
- [Apple: Managing your app's life cycle](URL) — confirms watchOS suspends tasks
- [SO #12345](URL) — community confirms workaround with unstructured Task

Research Pitfalls

Don't Over-Research

• •Set a time box: 2-3 queries max per unknown
• •If official docs don't have the answer after 2 searches, pivot to experimentation
• •Don't research things you can verify faster by reading the codebase

Don't Blindly Copy

• •External code samples may use deprecated APIs
• •Stack Overflow answers may be for different framework versions
• •Always adapt patterns to the project's existing conventions

Verify Recency

• •Check the date on sources — APIs change
• •Prefer documentation that matches the project's minimum deployment target
• •Watch for "updated for Swift 6" vs "Swift 5" differences

Integration with Other Skills