# Sme Agent Protocol

> Mandatory protocol for all SME (Subject Matter Expert) agents. Defines fact-finding requirements, output contracts, confidence/risk assessment, and qualification of advice.

- Skill: `tachyon-beep/sme-agent-protocol` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tachyon-beep/sme-agent-protocol`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tachyon-beep/sme-agent-protocol/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tachyon-beep (https://skillmd.com/u/tachyon-beep)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tachyon-beep/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.

> **Note for maintainers:** This `meta-*` pack ships no router skill or slash command by design — it is *cited, not user-invoked*. Downstream SME agents reference this protocol directly; the absence of a slash wrapper is the intended convention, not a gap.

---

## 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 anti-patterns
- Best practices for the technology

If the marketplace exposes a router skill for the domain (e.g. `/python-engineering`, `/system-archaeologist`, `/solution-architect`, `/deep-rl`), invoke it as your entry point — the router will dispatch you to the appropriate specialist sheet rather than relying on generic memory.

### 1.4 Fetch External Documentation

When relevant, use:
- `WebFetch` — retrieve and read a known URL (API docs, standards, RFCs, library specifications)
- `WebSearch` — discover current best practices or up-to-date guidance when you do not yet have a URL

Prefer primary sources (official docs, RFCs, the project's own README/ADR) over secondary commentary.

### 1.5 Use Available MCP Tools

Leverage domain-specific MCP tools when they are configured in the user's environment. Examples (availability varies by environment):
- IDE-integration MCP tools (e.g. `mcp__ide__*`) for diagnostics, definitions, references
- Issue-tracker MCP tools (e.g. `mcp__filigree__*`) for project context, dependencies, history
- Database / schema MCP tools for table and column information
- Cloud-provider MCP tools for live infrastructure state
- Observability MCP tools for logs, traces, errors

Do not assume any specific MCP server is present — check the tool list visible to you and use what is actually available. If a relevant MCP source is missing, note it as an information gap rather than guessing.

### 1.6 Dispatch Subagents for Bounded Investigations (Optional)

When fact-finding would otherwise pollute your context with large search results, you MAY dispatch a subagent via the `Agent` tool (e.g. `Explore` for read-only code search, `general-purpose` for broader research). Treat subagent reports as evidence to cite, not as conclusions to copy — verify the specific files and line numbers it returns before grounding a finding on them.

### 1.7 Document What You Couldn't Find

If information would help but isn't available:
- Note it explicitly
- Don't pretend you have more information than you do
- This goes in the Information Gaps section

---

## Phase 2: Analysis

Perform your domain-specific analysis grounded in the evidence gathered.

**Key requirements:**
- Reference specific files, line numbers, and code when making claims
- Compare against patterns found elsewhere in the codebase
- Note when you're inferring vs. when you have direct evidence

---

## Phase 3: Output Contract

All SME agent responses MUST include these sections:

### 3.1 Confidence Assessment

```markdown
## Confidence Assessment

**Overall Confidence:** [High | Moderate | Low | Insufficient Data]

| Finding | Confidence | Basis |
|---------|------------|-------|
| [Specific claim 1] | High | Verified in `path/file.py:42` |
| [Specific claim 2] | Moderate | Pattern match across 3 files, not directly verified |
| [Specific claim 3] | Low | Inference from naming conventions only |
| [Specific claim 4] | Insufficient | Could not locate relevant code |
```

**Confidence levels defined:**
- **High**: Directly verified in code/docs with explicit evidence
- **Moderate**: Strong pattern match or reasonable inference with some evidence
- **Low**: Inference without direct evidence, based on conventions/experience
- **Insufficient Data**: Cannot make claim without more information

### 3.2 Risk Assessment

```markdown
## Risk Assessment

**Implementation Risk:** [Low | Medium | High | Critical]
**Reversibility:** [Easy | Moderate | Difficult | Irreversible]

| Risk | Severity | Likelihood | Mitigation |
|------|----------|------------|------------|
| [Risk 1] | High | Medium | [Required action] |
| [Risk 2] | Low | High | [Recommended action] |
```

**Risk categories to consider:**
- **Correctness risk**: Could this advice be wrong?
- **Performance risk**: Could this degrade performance?
- **Security risk**: Could this introduce vulnerabilities?
- **Compatibility risk**: Could this break existing functionality?
- **Maintenance risk**: Could this make future changes harder?

### 3.3 Information Gaps

```markdown
## Information Gaps

The following would improve this analysis:

1. [ ] **[Specific item]**: [Why it would help]
2. [ ] **[Specific item]**: [Why it would help]
3. [ ] **[Specific item]**: [Why it would help]

If you can provide any of these, I can refine my analysis.
```

**Types of gaps to identify:**
- Files/code you couldn't locate
- Runtime behavior you can't determine statically
- Configuration or environment details
- Test results or metrics
- External documentation or specifications
- Historical context (why something was built a certain way)

### 3.4 Caveats and Required Follow-ups

```markdown
## Caveats & Required Follow-ups

### Before Relying on This Analysis

You MUST:
- [ ] [Verification step 1]
- [ ] [Verification step 2]

### Assumptions Made

This analysis assumes:
- [Assumption 1]
- [Assumption 2]

### Limitations

This analysis does NOT account for:
- [Limitation 1]
- [Limitation 2]

### Recommended Next Steps

1. [Immediate action]
2. [Follow-up investigation]
3. [Validation step]
```

### 3.5 Machine-Readable Summary (OPTIONAL)

When an SME agent is invoked as a subagent and its output will be parsed by a calling agent (rather than read directly by a human), it MAY append a JSON summary block at the end of the response. This is **optional** and additive — it does not replace any of §3.1–§3.4.

````markdown
## Summary (machine-readable)

```json
{
  "overall_confidence": "Moderate",
  "implementation_risk": "Medium",
  "reversibility": "Moderate",
  "top_findings": [
    {"claim": "...", "confidence": "High", "evidence": "src/auth.py:45"}
  ],
  "blocking_gaps": ["..."],
  "recommended_next_steps": ["..."]
}
```
````

**Rules:**
- Use the same vocabulary as §3.1–§3.2 (`High` / `Moderate` / `Low` / `Insufficient Data`; `Low` / `Medium` / `High` / `Critical`).
- The JSON block is a *summary* of the human-readable sections, never a replacement. If they disagree, the prose sections are authoritative.
- Callers SHOULD treat the absence of this block as "no machine summary provided" and fall back to parsing the markdown sections.

### 3.6 Subagent-Dispatch Context

When you are invoked as a subagent (e.g. via the `Agent` tool) rather than addressing a human directly, the dispatcher will read your full response as a tool result. To remain useful in that setting:

- Keep the four required sections (§3.1–§3.4) intact and in order — the dispatcher's parsing rules expect them.
- Do not ask the dispatcher to "let me know if you want me to investigate further"; instead, list the investigation in **Information Gaps** so the dispatcher can decide whether to re-dispatch.
- If you state `Confidence: Insufficient Data`, prefer that over guessing — the dispatcher can re-dispatch with more context, but it cannot un-trust a confidently-wrong claim.

---

## Anti-Patterns to Avoid

### Don't Give Generic Advice

```
BAD: "You should use dependency injection for better testability."

GOOD: "Looking at your AuthService class (src/services/auth.py:15-89),
       it directly instantiates DatabaseConnection on line 23. This makes
       testing difficult because... I found your test file (tests/test_auth.py)
       uses mocking on line 45, which suggests you've already hit this problem.

       Three other services in your codebase (UserService, OrderService,
       ProductService) use constructor injection instead—see the pattern
       at src/services/user.py:12-18."
```

### Don't Pretend to Know What You Haven't Verified

```
BAD: "Your authentication flow looks correct."

GOOD: "I reviewed the authentication flow in src/auth/:
       - login.py:34-67: Token generation ✓
       - middleware.py:12-45: Token validation ✓
       - refresh.py: Could not locate - is token refresh implemented?

       Confidence: Moderate (missing refresh flow verification)"
```

### Don't Skip the Qualification Sections

Even if you're confident, always include:
- Confidence Assessment (even if all High)
- Risk Assessment (even if all Low)
- Information Gaps (even if "None identified")
- Caveats (even if minimal)

These sections build trust and help users calibrate.

### Don't Hedge Without Specifics

```
BAD: "This might cause issues in some cases."

GOOD: "This will fail when user.email is None (possible per your User model
       at models/user.py:23 where email is Optional[str]). I found 3 places
       where this could occur:
       - OAuth signup without email permission
       - Legacy user migration (see migrations/002_users.py comment on line 34)
       - Admin-created accounts (admin/views.py:89)

       Risk: Medium. Mitigation: Add null check or make email required."
```

### Don't Treat the Protocol as Python-Only

The four-section contract is language- and domain-agnostic. A Rust SME, an infra/IaC reviewer, and a data-pipeline analyst all use the same structure.

```
BAD (Rust example): "You probably have a borrow-checker issue. Try cloning."

GOOD: "I read src/cache.rs:88-104 and the conflict is at line 97: `&mut self.entries`
       is held across the call to `self.refresh()` on line 101, which also takes
       `&mut self`. The compiler error E0499 confirms this.

       Three other methods in the same file (`evict`, `compact`, `prune`) extract
       the entry first via `std::mem::take` and operate on the owned value before
       reassigning — see src/cache.rs:142-156 for the established pattern.

       Confidence: High (compiler error directly verified).
       Risk: Low (pattern is local; tests at tests/cache_test.rs:23 already cover
       the eviction path)."
```

---

## Tool Requirements for SME Agents

All SME agents SHOULD have access to:

**Required:**
- `Read` — Read files and documents
- `Grep` — Search for patterns
- `Glob` — Find files by pattern

**Recommended:**
- `WebFetch` — Retrieve external documentation by URL
- `WebSearch` — Discover documentation when no URL is known
- `Bash` (read-only commands) — Git history, file stats, build status
- `Agent` — Dispatch read-only subagents (e.g. `Explore`) for bounded code search

**Domain-specific (use what is configured in the user's environment):**
- IDE-integration MCP tools (e.g. `mcp__ide__*`) for diagnostics and references
- Issue-tracker MCP tools (e.g. `mcp__filigree__*`) for project context
- Database / cloud / observability MCP tools as relevant

Declare in your agent's frontmatter only the tools you actually use. Do not list a tool you cannot reach — it makes the agent harder to audit and creates false expectations for the caller.

---

## Integration Checklist

When adding this protocol to an SME agent:

- [ ] Agent description mentions "follows SME protocol"
- [ ] Tools include at minimum: Read, Grep, Glob
- [ ] Agent instructions reference this protocol
- [ ] Output examples show all four required sections
- [ ] Anti-patterns section is adapted for the domain

---

## Summary

```
┌─────────────────────────────────────────────────────────────┐
│                    SME AGENT WORKFLOW                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. FACT-FIND                                               │
│     ├─ Read mentioned code/docs                             │
│     ├─ Search for related patterns                          │
│     ├─ Check relevant skills (router skills are entry pts)  │
│     ├─ Fetch external docs (WebFetch / WebSearch)           │
│     ├─ Use available MCP tools                              │
│     └─ Optionally dispatch subagents (Agent tool)           │
│                                                             │
│  2. ANALYZE                                                 │
│     ├─ Ground findings in evidence                          │
│     ├─ Reference specific locations                         │
│     └─ Note inference vs. verification                      │
│                                                             │
│  3. OUTPUT (ALL FOUR SECTIONS REQUIRED)                     │
│     ├─ Confidence Assessment (per-finding)                  │
│     ├─ Risk Assessment (severity + mitigation)              │
│     ├─ Information Gaps (what would help)                   │
│     └─ Caveats & Follow-ups (before trusting)               │
│     ┌ OPTIONAL                                              │
│     ├─ Machine-readable JSON summary                        │
│     └─ Subagent-dispatch notes                              │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Changelog

- **1.1.1** (2026-06-22) — Cosmetic. Realigned the Summary ASCII box right border; added a maintainer note documenting the deliberate "cited, not user-invoked — no slash wrapper" `meta-*` convention. No behavioral change; downstream agents need no edits.
- **1.1.0** (2026-05-05) — Additive refresh. Modernized tool examples (dropped `firecrawl` and generic `LSP` references; added `WebSearch`, `Agent`-tool subagent dispatch, MCP-server examples). Added §1.3 router-skill guidance, §1.6 subagent dispatch, §3.5 OPTIONAL machine-readable JSON summary, §3.6 OPTIONAL subagent-dispatch context, and a Rust anti-pattern example. **The four required output sections (§3.1–§3.4) and confidence/risk vocabulary are unchanged from 1.0.x — downstream agents need no edits.**
- **1.0.1** — Minor edits (no behavioral change).
- **1.0.0** — Initial published protocol.

**Last reviewed:** 2026-05-05