synaptiai Evidence-Based Development
Iron Law
EVIDENCE BEFORE CLAIMS, ALWAYS. If you haven't read the code, you don't know what it does.
No recommendation without a citation. No behavioral claim without verification. Confidence is not evidence.
Show Before Decide
Never propose a change without first showing the current state: "Here's what I found at file.rb:42 → here's what I recommend → here's why."
Citation Requirements
Every claim about code carries a file_path:line_number reference. When reviewing diffs, cite the file and the specific hunk. When reporting issues, show the exact code snippet.
Finding Prioritization
All findings, review comments, and issues use P1/P2/P3. This operationalizes the organizational hard boundary "No Ungrounded Claims": every finding carries evidence (file:line, test output, runtime observation) proportional to its priority.
| Priority | Meaning | Action |
|---|---|---|
| P1 | Must fix — blocks merge, security issue, data loss risk, broken functionality | Fix before proceeding |
| P2 | Should fix — logic error, missing edge case, test gap, convention violation | Fix in this PR |
| P3 | Consider — style preference, optimization opportunity | Fix in-PR by default. Cosmetic P3 in untouched files: fix-if-bounded or document inline (default) / follow-up issue (minimalScope mode only). Finding triage is NEVER a valid escalation trigger — see skills/llm-operator-principles/SKILL.md. |
ASSERTION/EVIDENCE/VERIFIED Pattern
For any non-trivial claim about code behavior (behavioral claims, security assessments, performance analysis — not obvious facts):
- ASSERTION: what you believe to be true
- EVIDENCE: the code/output/test that supports it
- VERIFIED: confirmed by running a test, reading the actual code, or checking behavior
Finding-First Display
Show findings BEFORE recommendations or actions: the finding table (sorted P1 → P2 → P3), then affected files with citations, then proposed actions, then decisions (if needed). Never bury findings after narrative.
Deduplication
When synthesizing findings from multiple sources (agents, reviews, tools): deduplicate by file:line; keep the highest priority; merge descriptions that add context; note each finding's source.
Verification Methods
Run tests after code changes. Read code or git diff before behavioral claims and after edits. Run independent checks as parallel Bash calls. Use Agent(Explore) for unfamiliar code in a separate context.
Stop Conditions
Stop and reassess when: you've made 2+ claims without file:line citations; you're about to recommend a change to a file you haven't read; evidence contradicts your assumption (update the assumption, don't explain away the evidence); you're writing "should" or "probably" about code behavior — go verify.
Graceful Degradation
When evidence is unavailable: state what you couldn't verify and why; proceed with reduced confidence, flagging assumptions; never fabricate evidence or cite files you haven't read. "I already checked earlier" is stale — show fresh evidence.