Skip to main content
skill CX Codex

sherlock-review — Claude Code skill: investigate code through evidence

sherlock-review is a skill for investigating code changes through evidence and deduction. It helps find bug root causes or verify fixes.

MIT 135 installs ★ 533 updated 2026-11-04

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add proffesor-for-testing/agentic-qe --skill sherlock-review -a claude-code
Open on GitHub

What sherlock-review does

The skill guides you through a structured method: gather evidence (code, tests, history), compare it against the claim, rule out impossibilities, render a verdict. Three verdict levels (supported, partially supported, contradicted) cut through hearsay.

Includes an investigation template, evidence checklist, and scenarios for common situations: did this actually fix the bug, does the claimed 50-percent speedup hold up, are all edge cases covered. The skill coordinates with agents qe-code-reviewer, qe-security-auditor, and qe-performance-validator, running them in parallel to validate different categories of claims.

Code and tests run locally—no leaning on commit messages. Each investigation surfaces at least three weighted findings; results store in the agent memory namespace aqe/sherlock/.

What it helps with

  • verify whether a bug was fixed or only silenced
  • confirm performance gains are real measurements, not artifacts
  • detect which boundary conditions lack test coverage
  • trace the root cause by analyzing code changes and git history
  • catch unsafe behavior hidden in production code

Example prompts for the agent

  • Investigate PR #42: does the evidence support the claim that it fixes a memory leak?
  • Apply Sherlock logic to commit abc123 — what evidence supports or contradicts the stated threefold speedup?
  • Gather evidence for the claim 'all edge cases are handled' and deliver your verdict

How to install sherlock-review

1Skills CLI (Vercel)

npx skills add proffesor-for-testing/agentic-qe --skill sherlock-review -a claude-code

2Manually: put the files in place

~/.claude/skills/sherlock-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/sherlock-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about sherlock-review

How do I install sherlock-review for Claude Code?

Run npx skills add proffesor-for-testing/agentic-qe --skill sherlock-review -a claude-code, then open ~/.claude/skills/sherlock-review/SKILL.md for quick reference.

What does sherlock-review do?

It systematically validates code claims by collecting evidence, applying deductive logic, and ruling out contradictions. Cuts through vague promises to find real bugs, confirm fixes, and measure actual behavior.

Which agents work with this skill?

The skill orchestrates qe-code-reviewer for code analysis, qe-security-auditor for security claims, and qe-performance-validator for performance benchmarks, all in parallel.

Source text

SKILL.md · MIT
---
name: sherlock-review
description: "Evidence-based investigative code review using deductive reasoning to determine what actually happened versus what was claimed. Use when verifying implementation claims, investigating bugs, validating fixes, or conducting root cause analysis. Elementary approach to finding truth through systematic observation."
category: quality-review
priority: high
tokenEstimate: 1100
agents: [qe-code-reviewer, qe-security-auditor, qe-performance-validator]
implementation_status: optimized
optimization_version: 1.0
last_optimized: 2025-12-03
dependencies: []
quick_reference_card: true
tags: [investigation, evidence-based, code-review, root-cause, deduction]
trust_tier: 2
validation:
  schema_path: schemas/output.json
  validator_path: scripts/validate-config.json
  eval_path: evals/sherlock-review.yaml
---
# Sherlock Review

<default_to_action>
When investigating code claims:
1. OBSERVE: Gather all evidence (code, tests, history, behavior)
2. DEDUCE: What does evidence actually show vs. what was claimed?
3. ELIMINATE: Rule out what cannot be true
4. CONCLUDE: Does evidence support the claim?
5. DOCUMENT: Findings with proof, not assumptions

**The 3-Step Investigation:**
```bash
# 1. OBSERVE: Gather evidence
git diff <commit>
npm test -- --coverage

# 2. DEDUCE: Compare claim vs reality
# Does code match description?
# Do tests prove the fix/feature?

# 3. CONCLUDE: Verdict with evidence
# SUPPORTED / PARTIALLY SUPPORTED / NOT SUPPORTED
```

**Holmesian Principles:**
- "Data! Data! Data!" - Collect before concluding
- "Eliminate the impossible" - What cannot be true?
- "You see, but do not observe" - Run code, don't just read
- Trust only reproducible evidence
</default_to_action>

## Quick Reference Card

### Evidence Collection Checklist

| Category | What to Check | How |
|----------|---------------|-----|
| **Claim** | PR description, commit messages | Read thoroughly |
| **Code** | Actual file changes | `git diff` |
| **Tests** | Coverage, assertions | Run independently |
| **Behavior** | Runtime output | Execute locally |
| **Timeline** | When things happened | `git log`, `git blame` |

### Verdict Levels

| Verdict | Meaning |
|---------|---------|
| ✓ **TRUE** | Evidence fully supports claim |
| ⚠ **PARTIALLY TRUE** | Claim accurate but incomplete |
| ✗ **FALSE** | Evidence contradicts claim |
| ? **NONSENSICAL** | Claim doesn't apply to context |
| … **UNVERIFIED** | Not enough evidence either way; state what would settle it |

---

## Investigation Template

```markdown
## Sherlock Investigation: [Claim]

### The Claim
"[What PR/commit claims to do]"

### Evidence Examined
- Code changes: [files, lines]
- Tests added: [count, coverage]
- Behavior observed: [what actually happens]

### Deductive Analysis

**Claim**: [specific assertion]
**Evidence**: [what you found]
**Deduction**: [logical conclusion]
**Verdict**: ✓/⚠/✗

### Findings
- What works: [with evidence]
- What doesn't: [with evidence]
- What's missing: [gaps in implementation/testing]

### Recommendations
1. [Action based on findings]
```

## Evidence Over Volume (No Findings Quota)
Every finding and every verdict must chain to observable evidence: code, command output, test results, history. There is no minimum number of observations. When the evidence supports the claim, the correct verdict is TRUE (the output schema's `case-closed-clean`), with a list of what was examined. Manufacturing clues to make an investigation look productive is the same failure Sherlock exists to catch. If the evidence is insufficient either way, say so, state what would settle it, and do not guess.

---

## Investigation Scenarios

### Scenario 1: "This Fixed the Bug"

**Steps:**
1. Reproduce bug on commit before fix
2. Verify bug is gone on commit with fix
3. Check if fix addresses root cause or symptom
4. Test edge cases not in original report

**Red Flags:**
- Fix that just removes error logging
- Works only for specific test case
- Workarounds instead of root cause fix
- No regression test added

### Scenario 2: "Improved Performance by 50%"

**Steps:**
1. Run benchmark on baseline commit
2. Run same benchmark on optimized commit
3. Compare in identical conditions
4. Verify measurement methodology

**Red Flags:**
- Tested only on toy data
- Different comparison conditions
- Trade-offs not mentioned

### Scenario 3: "Handles All Edge Cases"

**Steps:**
1. List all edge cases in code path
2. Check each has test coverage
3. Test boundary conditions
4. Verify error handling paths

**Red Flags:**
- `catch {}` swallowing errors
- Generic error messages
- No logging of critical errors

---

## Example Investigation

```markdown
## Case: PR #123 "Fix race condition in async handler"

### Claims Examined:
1. "Eliminates race condition"
2. "Adds mutex locking"
3. "100% thread safe"

### Evidence:
- File: src/handlers/async-handler.js
- Changes: Added `async/await`, removed callbacks
- Tests: 2 new tests for async flow
- Coverage: 85% (was 75%)

### Analysis:

**Claim 1: "Eliminates race condition"**
Evidence: Added `await` to sequential operations. No actual mutex.
Deduction: Race avoided by removing concurrency, not synchronization.
Verdict: ⚠ PARTIALLY TRUE (solved differently than claimed)

**Claim 2: "Adds mutex locking"**
Evidence: No mutex library, no lock variables, no sync primitives.
Verdict: ✗ FALSE

**Claim 3: "100% thread safe"**
Evidence: JavaScript is single-threaded. No worker threads used.
Verdict: ? NONSENSICAL (meaningless in this context)

### Conclusion:
Fix works but not for reasons claimed. Race condition avoided by
making operations sequential, not by adding synchronization.

### Recommendations:
1. Update PR description to accurately reflect solution
2. Add test for concurrent request handling
3. Remove incorrect technical claims
```

---

## Agent Integration

```typescript
// Evidence-based code review
await Task("Sherlock Review", {
  prNumber: 123,
  claims: [
    "Fixes memory leak",
    "Improves performance 30%"
  ],
  verifyReproduction: true,
  testEdgeCases: true
}, "qe-code-reviewer");

// Bug fix verification
await Task("Verify Fix", {
  bugCommit: 'abc123',
  fixCommit: 'def456',
  reproductionSteps: steps,
  testBoundaryConditions: true
}, "qe-code-reviewer");
```

---

## Agent Coordination Hints

### Memory Namespace
```
aqe/sherlock/
├── investigations/*   - Investigation reports
├── evidence/*         - Collected evidence
├── verdicts/*         - Claim verdicts
└── patterns/*         - Common deception patterns
```

### Fleet Coordination
```typescript
const investigationFleet = await FleetManager.coordinate({
  strategy: 'evidence-investigation',
  agents: [
    'qe-code-reviewer',        // Code analysis
    'qe-security-auditor',     // Security claim verification
    'qe-performance-validator' // Performance claim verification
  ],
  topology: 'parallel'
});
```

---

## Related Skills
- [brutal-honesty-review](../brutal-honesty-review/) - Direct technical criticism
- [context-driven-testing](../context-driven-testing/) - Adapt to context
- [bug-reporting-excellence](../bug-reporting-excellence/) - Document findings

---

## Remember

**"It is a capital mistake to theorize before one has data."** Trust only reproducible evidence. Don't trust commit messages, documentation, or "works on my machine."

**The Sherlock Standard:** Every claim must be verified empirically. What does the evidence actually show?

© proffesor-for-testing · MIT · proffesor-for-testing/agentic-qe

Similar skills

All skills for Code review and refactoring →

From the same set73

The whole set →
qe-requirements-validation qe-requirements-validation is a skill that checks acceptance criteria for testability, links requirements to test cases, and generates BDD scenarios from user stories before development. CX Codex +1 141installs refactoring-patterns Applies refactoring patterns. Runs when you need to improve code structure without changing behavior. CX Codex +1 140installs chaos-engineering-resilience chaos-engineering-resilience — a skill for injecting controlled failures into distributed systems, verifying recovery mechanisms, and validating resilience. Catches weaknesses before users do. CX Codex +1 138installs localization-testing The localization-testing skill checks translation coverage, locale-specific formats, RTL layouts, and Unicode handling. Use it when adding languages or preparing an international release. CX Codex +1 137installs wms-testing-patterns wms-testing-patterns is a Claude Code skill with patterns for testing inventory accuracy, pick waves, EDI documents, and WMS-ERP integration. CX Codex +1 134installs six-thinking-hats Applies Six Thinking Hats to test strategy, failure analysis, and retrospectives. It separates facts, risks, benefits, ideas, feelings, and next actions. CX Codex +1 131installs a11y-ally The a11y-ally skill audits pages for WCAG issues and suggests fixes based on page context. Use it to review a site or assess video accessibility. CX Codex +1 131installs contract-testing Guides consumer-driven contract testing for microservices using Pact, catching breaking API changes before deploy. CX Codex +1 130installs

Project sponsors

Companies that keep this analytics open