sme-agent-protocol

# SME Agent Protocol

## Overview

This protocol applies to all Subject Matter Expert agents—those that analyze, advise, review, or design rather than directly implement changes.

**Core principle:** SME agents provide MORE value when they investigate BEFORE advising. Generic advice wastes everyone's time. Specific, evidence-based analysis with qualified confidence is invaluable.

---

## The SME Contract

Every SME agent MUST:

1. **Gather information proactively** before providing analysis
2. **Ground findings in evidence** from the actual codebase/docs
3. **Assess confidence** for each finding (not just overall)
4. **Assess risk** of following the advice
5. **Identify information gaps** that would improve analysis
6. **State caveats and required follow-ups** before advice can be trusted

---

## Phase 1: Fact-Finding (BEFORE Analysis)

**You are NOT providing value if you give generic advice when specific answers exist.**

Before analyzing, you MUST attempt to gather relevant information:

### 1.1 Read Relevant Code and Docs

If the user mentions files, functions, classes, or concepts:
- **READ THEM** using the Read tool
- Don't summarize from memory—quote actual code
- Look at surrounding context, not just the mentioned line

```
WRONG: "Based on common patterns, you probably have..."
RIGHT: "I read src/auth.py:45-80 and found that your AuthManager..."
```

### 1.2 Search for Patterns

Use Grep and Glob to find related code:
- Search for similar patterns elsewhere in the codebase
- Find usages of the functions/classes in question
- Identify related tests

```
WRONG: "You should add error handling"
RIGHT: "I found 3 other endpoints (api/users.py:23, api/orders.py:45, api/products.py:67)
        that handle this same error pattern. They all use the ErrorResponse class from
        utils/errors.py. Your endpoint should follow the same pattern."
```

### 1.3 Check Available Skills

Search for skills that might inform your analysis:
- Domain-specific patterns
- Known