---
description: Epistemic integrity protocol for findings, recommendations, and validations
version: "1.0"
created: 2026-03-29
source: Prompt engineering patterns (Grounded Extraction, Loss Framing, Epistemic Provenance)
---

# Epistemic Integrity Protocol

Every recommendation, finding, and validation result produced by DevForgeAI agents MUST carry provenance classification and confidence assessment. This applies to ALL agents that produce findings, recommendations, or validation results.

---

## Provenance Classification

| Classification | Definition | Evidence Required | Example |
|---------------|-----------|-------------------|---------|
| **GROUNDED** | Directly supported by artifacts the agent has read | Context file content, test output, Read() file content, explicit user input | "TypeScript required (Source: tech-stack.md, lines 12-14)" |
| **DERIVED** | Reached through inference, heuristics, or cross-reference | One-sentence justification required | "Likely a God Object (DERIVED: class has 23 methods across 3 unrelated domains)" |
| **INCONCLUSIVE** | Evidence insufficient to determine | Reason for insufficiency required | "Coverage impact unknown (INCONCLUSIVE: no test runner output available for this module)" |

---

## Loss Framing Rule

A wrong finding is 3x worse than admitting uncertainty:

| Outcome | Cost | Example |
|---------|------|---------|
| Correct GROUNDED finding | 0 (ideal) | Correctly identifies anti-pattern with file:line evidence |
| Correct INCONCLUSIVE flag | 1x (acceptable) | Flags coverage gap as uncertain when test output unavailable |
| Wrong finding (false positive) | **3x** (costly) | Reports anti-pattern violation that does not exist |
| Wrong finding (fabricated gap) | **3x** (costly) | Claims coverage is below threshold without running tests |
| Wrong recommendation | **3x** (costly) | Recommends technology not in tech-stack.md |

**Behavioral rule:** When confidence is below the applicable threshold, flag as INCONCLUSIVE rather than guessing.

### Confidence Thresholds by Subagent

| Subagent | Existing Mechanism | INCONCLUSIVE Trigger |
|----------|-------------------|---------------------|
| ac-compliance-verifier | HIGH/MEDIUM/LOW confidence with DIRECT/INFERRED/PARTIAL match types | LOW confidence + PARTIAL match_type |
| code-reviewer | 0.7 confidence threshold for placeholder detection | Below 0.7 = SUPPRESS (valid_pattern) |
| diagnostic-analyst | Hypothesis confidence scores (0.0-1.0) | Hypotheses below 0.5 confidence |
| All other agents | No existing threshold | Cannot cite specific file, line, or test output to support finding |

---

## Integration with Existing Patterns

### Grounding Protocol (extends citation-requirements.md)

The Read-Quote-Cite-Verify protocol enforces GROUNDED provenance for technology and architecture recommendations. This protocol extends that to ALL findings:

- **MUST cite** categories (from citation-requirements.md) produce GROUNDED findings
- **SHOULD cite** categories produce GROUNDED findings when cited, DERIVED when not
- Findings without any citation are DERIVED and require justification
- Findings where investigation was attempted but evidence not found are INCONCLUSIVE

### Match Types (extends ac-compliance-verifier scoring-methodology.md)

| Existing Match Type | Maps To |
|--------------------|---------|
| DIRECT | GROUNDED |
| INFERRED | DERIVED |
| PARTIAL (LOW confidence) | INCONCLUSIVE |
| PARTIAL (MEDIUM confidence) | DERIVED |

### Diagnostic Status (extends diagnostic-analyst.md)

| Existing Status | Maps To |
|----------------|---------|
| DIAGNOSED | Contains GROUNDED findings |
| INCONCLUSIVE | INCONCLUSIVE |
| ESCALATED | INCONCLUSIVE + HALT |

---

## HALT Triggers

These conditions are judgment calls — no hook can detect them. HALT and use AskUserQuestion when about to report a CRITICAL or HIGH severity finding that is DERIVED (not GROUNDED), about to recommend a technology change based on DERIVED reasoning, or when evidence contradicts itself (context file says X, code says Y — flag INCONCLUSIVE).

---

## References

- **Citation Requirements:** `.claude/rules/core/citation-requirements.md` (Grounding Protocol)
- **AC Compliance Verifier Scoring:** `.claude/agents/ac-compliance-verifier/references/scoring-methodology.md`
- **Diagnostic Analyst:** `.claude/agents/diagnostic-analyst.md` (DIAGNOSED/INCONCLUSIVE/ESCALATED status)
- **Code Reviewer:** `.claude/agents/code-reviewer.md` (0.7 confidence threshold)
