docs(coding,review): require fact vs. judgment labeling in review and triage findings
Summary
Directive review flows (deft-directive-review-cycle, deft-directive-gh-triage, pre-PR loop) produce findings that mix observable facts with subjective judgments without distinguishing them. A reviewer can legitimately dismiss "this module feels too complex" but cannot dismiss "src/auth/token.py:87 accepts expired tokens because expiry is never checked." Requiring agents to label every finding as Fact or Judgment reduces speculative noise, makes findings harder to reject without evidence, and improves review quality.
The distinction
Fact: an observable, verifiable claim grounded in a specific file and line.
Example: "src/api/client.ts:142 -- this function has no error handling; any network failure will propagate as an unhandled exception."
Judgment: an interpretation or opinion about design, architecture, or style that reasonable engineers could disagree about.
Example: "this module feels unclear in its responsibilities."
Both are valid findings. The difference is in how they should be responded to:
- Facts require a fix or an explicit documented exception
- Judgments require a discussion before action
Proposed changes
coding/coding.md -- add a named principle: every finding in a code review or audit output MUST be labeled Fact or Judgment. Facts must include file:line evidence. Judgments must include the reasoning.
skills/deft-directive-review-cycle/SKILL.md -- add the labeling requirement to the findings format. P0/P1 findings that cannot be supported with file:line evidence must be downgraded to P2 or labeled Judgment.
skills/deft-directive-gh-triage/SKILL.md -- add the labeling requirement to the triage output format. Root cause claims must be labeled Fact (with evidence) or Hypothesis (with supporting reasoning).
Acceptance criteria
- coding/coding.md states the fact/judgment distinction as a named principle
- Review cycle findings are labeled Fact (with file:line) or Judgment (with reasoning)
- Triage root cause claims are labeled Fact or Hypothesis
- A finding labeled Fact without a file:line citation fails the review format check
Related
Source
@meta_alchemist repo audit prompt (https://x.com/meta_alchemist/status/2064431279383433646, 2,419 bookmarks, June 9 2026): "Distinguish facts (this function has no error handling: src/api/client.ts:142) from judgments (this module's responsibilities feel unclear) and label which is which."
docs(coding,review): require fact vs. judgment labeling in review and triage findings
Summary
Directive review flows (deft-directive-review-cycle, deft-directive-gh-triage, pre-PR loop) produce findings that mix observable facts with subjective judgments without distinguishing them. A reviewer can legitimately dismiss "this module feels too complex" but cannot dismiss "src/auth/token.py:87 accepts expired tokens because expiry is never checked." Requiring agents to label every finding as Fact or Judgment reduces speculative noise, makes findings harder to reject without evidence, and improves review quality.
The distinction
Fact: an observable, verifiable claim grounded in a specific file and line.
Example: "src/api/client.ts:142 -- this function has no error handling; any network failure will propagate as an unhandled exception."
Judgment: an interpretation or opinion about design, architecture, or style that reasonable engineers could disagree about.
Example: "this module feels unclear in its responsibilities."
Both are valid findings. The difference is in how they should be responded to:
Proposed changes
coding/coding.md -- add a named principle: every finding in a code review or audit output MUST be labeled Fact or Judgment. Facts must include file:line evidence. Judgments must include the reasoning.
skills/deft-directive-review-cycle/SKILL.md -- add the labeling requirement to the findings format. P0/P1 findings that cannot be supported with file:line evidence must be downgraded to P2 or labeled Judgment.
skills/deft-directive-gh-triage/SKILL.md -- add the labeling requirement to the triage output format. Root cause claims must be labeled Fact (with evidence) or Hypothesis (with supporting reasoning).
Acceptance criteria
Related
Source
@meta_alchemist repo audit prompt (https://x.com/meta_alchemist/status/2064431279383433646, 2,419 bookmarks, June 9 2026): "Distinguish facts (this function has no error handling: src/api/client.ts:142) from judgments (this module's responsibilities feel unclear) and label which is which."