docs: Dorian's best use case (2026-06-27) — agent change-note receipts (evidence-backed, judged)#23
Merged
Conversation
…ce-backed Discovery package for Dorian's highest-leverage wedge, from a multi-agent web-research pass (37 cited sources), real-repo trials on the published dorian-vwp 1.2.0, a competitive analysis, adversarial critique, and an independent fresh-context judge (ACCEPT). Chosen wedge (A, refined): "Receipts for what your AI coding agent claimed it changed" — turn the CHECKABLE subset of an agent's change summary (especially the no-failing-test facts: config, signatures, constants, references) into deterministic git .warrant receipts that are born-verifiable now and REVOKE on later drift; token-free. Primary user: the solo Claude Code / AI-agent power user; channel: a final-message claims.json convention + the GitHub Action. Secondary: PR-summary rot (B) and executable-docs drift (E) as the same mechanism. Rejected F/G/H (provenance / ML-metric / untrusted-fork — the last a trust-boundary inversion). Deliverables: BEST_USE_CASE_2026_06_27.md, USE_CASE_DECISION_MATRIX_2026_06_27.md, DEMO_SCRIPT_BEST_USE_CASE.md (proven <3-min demo on python-dotenv), CLAUDE_CODE_DORIAN_WORKFLOW.md, POSITIONING_2026_06_27.md. Honest throughout: checkable-subset only, not a sandbox/LLM-judge, trigger-vs-truth preserved, unsigned-warrant + authoring-friction limits disclosed. Dogfooded: docs/changes/best-use-case-discovery.md sealed under --strength-gate=fail (6/6) — v1.2.0, zero-dep core, the CLI `revalidate` command the demo uses, and the SECURITY_BOUNDARY not-a-sandbox boundary, all warranted. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
📝 WalkthroughWalkthroughAdds five new documentation files defining Dorian's primary use case as an AI-agent change-note verifier. Includes a dated best-use-case narrative, a decision matrix, positioning copy, an agent workflow guide, a copy-paste demo script, and a self-referential change note with a sealed ChangesBest Use Case Documentation Package
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
docs/CLAUDE_CODE_DORIAN_WORKFLOW.md (1)
87-96: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd language specifier to fenced code block.
The template code block triggers markdownlint MD040. Add
markdownortext:+```markdown
What I changed
Checkable receipts (dorian)
I emit claims.json with these load-bearing, checker-backed claims:
- : — <C3/C4/C5 program>
(only statements a deterministic checker can falsify; prose is excluded)
Run: dorian verify --claims claims.json --strength-gate=fail+```🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/CLAUDE_CODE_DORIAN_WORKFLOW.md` around lines 87 - 96, The fenced template block in the workflow doc is missing a language specifier, which triggers markdownlint MD040. Update the fenced code block around the “What I changed” and “Checkable receipts (dorian)” template to include an explicit language tag such as markdown or text, keeping the existing content unchanged.Source: Linters/SAST tools
docs/USE_CASE_DECISION_MATRIX_2026_06_27.md (1)
12-16: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd language specifier to fenced code block.
The weighted formula block triggers markdownlint MD040. Add
textorpythonto silence the warning and improve renderer compatibility.+```text
weighted = 2.0pain + 1.5dorian_fit + 1.5demo_clarity + 1.2adoption_friction_inverse
+ 1.2evidence_strength + 1.0differentiation + 1.0frequency + 0.8urgency
+ 0.8trust_boundary_fit + 0.5expansion_potential
- 1.5overclaiming_risk - 1.0implementation_gap+```🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/USE_CASE_DECISION_MATRIX_2026_06_27.md` around lines 12 - 16, Add a language specifier to the fenced formula block to satisfy markdownlint MD040 and improve rendering; update the markdown fence around the weighted expression in USE_CASE_DECISION_MATRIX_2026_06_27.md to use a proper hint like text or python, keeping the existing content unchanged. Locate the block by the weighted formula text and ensure the opening and closing fences are balanced after the change.Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/BEST_USE_CASE_2026_06_27.md`:
- Line 25: The arXiv citation in the BEST_USE_CASE_2026_06_27 document appears
to have an invalid year prefix, so update the reference to the correct paper
identifier. Check the citation text containing arXiv 2601.04886 and replace it
with the verified arXiv ID/year after confirming the intended source. Keep the
surrounding sentence unchanged and only correct the citation string.
In `@docs/changes/best-use-case-discovery.md.warrant`:
- Around line 7-8: The sealed artifact reference is inconsistent with the
documented content: the current git_ref does not include
docs/changes/best-use-case-discovery.md, so the content_hash cannot be
reproduced. Update the git_ref to a commit that actually contains the file, or
reseal the artifact from the commit that owns best-use-case-discovery.md,
ensuring the warrant metadata stays aligned with the sealed content.
In `@docs/DEMO_SCRIPT_BEST_USE_CASE.md`:
- Around line 76-80: The dorian revalidate example in the demo script does not
match the actual text formatter output, so update the transcript to use the real
text format produced by the revalidate flow. Adjust the example around the
revalidate command and its reported results so it starts with the checked
summary, removes the leading comment markers, and omits the inline exit
annotation; use the existing revalidate output formatting as the source of
truth.
---
Nitpick comments:
In `@docs/CLAUDE_CODE_DORIAN_WORKFLOW.md`:
- Around line 87-96: The fenced template block in the workflow doc is missing a
language specifier, which triggers markdownlint MD040. Update the fenced code
block around the “What I changed” and “Checkable receipts (dorian)” template to
include an explicit language tag such as markdown or text, keeping the existing
content unchanged.
In `@docs/USE_CASE_DECISION_MATRIX_2026_06_27.md`:
- Around line 12-16: Add a language specifier to the fenced formula block to
satisfy markdownlint MD040 and improve rendering; update the markdown fence
around the weighted expression in USE_CASE_DECISION_MATRIX_2026_06_27.md to use
a proper hint like text or python, keeping the existing content unchanged.
Locate the block by the weighted formula text and ensure the opening and closing
fences are balanced after the change.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 5bd91481-c0fd-4b9a-b7c6-06ff9db49288
📒 Files selected for processing (8)
docs/BEST_USE_CASE_2026_06_27.mddocs/CLAUDE_CODE_DORIAN_WORKFLOW.mddocs/DEMO_SCRIPT_BEST_USE_CASE.mddocs/POSITIONING_2026_06_27.mddocs/USE_CASE_DECISION_MATRIX_2026_06_27.mddocs/changes/best-use-case-discovery.claims.jsondocs/changes/best-use-case-discovery.mddocs/changes/best-use-case-discovery.md.warrant
| authoring time**, the seal is **born-verifiable**: it refuses to seal any claim that is *already* false | ||
| right now (exit 4) — directly catching the "**phantom change**" failure where an agent's description | ||
| asserts an edit the code does not actually contain, which an academic study finds is the single most | ||
| common message-code inconsistency (**~45%**, [arXiv 2601.04886](https://arxiv.org/abs/2601.04886)). |
There was a problem hiding this comment.
🎯 Functional Correctness | 🔴 Critical | ⚡ Quick win
Fix arXiv citation year — "2601" appears to be a typo.
The citation reads arXiv 2601.04886 but 2601 is >600 years in the future. Verify the correct year (likely 2025 or 2026) and fix.
- ([arXiv 2601.04886](https://arxiv.org/abs/2601.04886)). GitHub's own docs admit
+ ([arXiv 2025.04886](https://arxiv.org/abs/2025.04886)). GitHub's own docs admitOr verify the actual ID:
#!/bin/bash
curl -sI "https://arxiv.org/abs/2601.04886" | head -5
curl -sI "https://arxiv.org/abs/2501.04886" | head -5
curl -sI "https://arxiv.org/abs/2401.04886" | head -5🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/BEST_USE_CASE_2026_06_27.md` at line 25, The arXiv citation in the
BEST_USE_CASE_2026_06_27 document appears to have an invalid year prefix, so
update the reference to the correct paper identifier. Check the citation text
containing arXiv 2601.04886 and replace it with the verified arXiv ID/year after
confirming the intended source. Keep the surrounding sentence unchanged and only
correct the citation string.
Comment on lines
+7
to
+8
| "content_hash": "sha256:70ae592528abff9f2a7a52262aea4884c2666d4f9319cce366119c1c5fa13467", | ||
| "git_ref": "0e99d46ad84acb916fa3dc5b5655602bc878db7f" |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if git ref exists
git cat-file -t 0e99d46ad84acb916fa3dc5b5655602bc878db7f 2>/dev/null && echo "git ref exists" || echo "FAIL: git ref not found"
# Verify content hash of the change note (should match line 7)
git show 0e99d46ad84acb916fa3dc5b5655602bc878db7f:docs/changes/best-use-case-discovery.md 2>/dev/null | sha256sumRepository: ajaysurya1221/dorian
Length of output: 227
🏁 Script executed:
#!/bin/bash
set -euo pipefail
ref=0e99d46ad84acb916fa3dc5b5655602bc878db7f
path=docs/changes/best-use-case-discovery.md
git cat-file -t "$ref"
python3 - <<'PY'
import hashlib, subprocess, sys
ref = "0e99d46ad84acb916fa3dc5b5655602bc878db7f"
path = "docs/changes/best-use-case-discovery.md"
content = subprocess.check_output(["git", "show", f"{ref}:{path}"])
digest = hashlib.sha256(content).hexdigest()
print(digest)
PYRepository: ajaysurya1221/dorian
Length of output: 859
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== warrant file ==\n'
cat -n docs/changes/best-use-case-discovery.md.warrant | sed -n '1,120p'
printf '\n== commit tree paths ==\n'
git ls-tree -r --name-only 0e99d46ad84acb916fa3dc5b5655602bc878db7f | sed -n '1,200p'Repository: ajaysurya1221/dorian
Length of output: 10868
git_ref must include the sealed artifact — 0e99d46ad84acb916fa3dc5b5655602bc878db7f exists, but it does not contain docs/changes/best-use-case-discovery.md, so the stated content_hash can’t be reproduced from this ref. Update the ref or seal the file from the commit that actually contains it.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/changes/best-use-case-discovery.md.warrant` around lines 7 - 8, The
sealed artifact reference is inconsistent with the documented content: the
current git_ref does not include docs/changes/best-use-case-discovery.md, so the
content_hash cannot be reproduced. Update the git_ref to a commit that actually
contains the file, or reseal the artifact from the commit that owns
best-use-case-discovery.md, ensuring the warrant metadata stays aligned with the
sealed content.
Comment on lines
+76
to
+80
| dorian revalidate --since HEAD~1 | ||
| # BROKEN load-dotenv-default-override-false C3: signature_mismatch: load_dotenv: default of 'override': 'True' != expected 'False' | ||
| # VERIFIED dotenv-values-exists | ||
| # fold WARRANTED -> REVOKED (exit 4) | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
ast-grep outline src/dorian/revalidate.py --match "cmd_revalidate" --view expanded 2>/dev/null || rg -A 30 "def cmd_revalidate" src/dorian/revalidate.pyRepository: ajaysurya1221/dorian
Length of output: 197
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Find likely command entry points and output format strings for revalidate
rg -n --hidden --glob '!**/.git/**' -e 'cmd_revalidate|revalidate\b|BROKEN|VERIFIED|WARRANTED|REVOKED|signature_mismatch|load-dotenv-default-override-false' src docs . 2>/dev/null | head -n 200
# Map candidate source files that mention revalidate
fd -i 'revalidate' src docs 2>/dev/null || trueRepository: ajaysurya1221/dorian
Length of output: 21880
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect revalidate command wiring and output formatting
sed -n '780,860p' src/dorian/commands.py
printf '\n--- revalidate.py ---\n'
sed -n '330,470p' src/dorian/revalidate.py
printf '\n--- demo doc snippet ---\n'
sed -n '68,86p' docs/DEMO_SCRIPT_BEST_USE_CASE.mdRepository: ajaysurya1221/dorian
Length of output: 9975
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Check the default output format for `dorian revalidate`
sed -n '180,260p' src/dorian/cli.pyRepository: ajaysurya1221/dorian
Length of output: 4083
Update the dorian revalidate example to match the text formatter. docs/DEMO_SCRIPT_BEST_USE_CASE.md:76-80 should show the actual text output (checked ... first, no leading # prefixes, and no inline (exit 4)), otherwise the transcript is misleading.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/DEMO_SCRIPT_BEST_USE_CASE.md` around lines 76 - 80, The dorian
revalidate example in the demo script does not match the actual text formatter
output, so update the transcript to use the real text format produced by the
revalidate flow. Adjust the example around the revalidate command and its
reported results so it starts with the checked summary, removes the leading
comment markers, and omits the inline exit annotation; use the existing
revalidate output formatting as the source of truth.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
An evidence-backed discovery of Dorian's single highest-leverage use case, with operational deliverables.
Process: a multi-agent web-research workflow (5 questions + competitive matrix + 8 scored candidates + adversarial critique; 37 cited sources), real-repo trials on the published
dorian-vwp1.2.0 (python-dotenv @751f8c1), and an independent fresh-context judge → ACCEPT.The wedge (A, refined)
"Receipts for what your AI coding agent claimed it changed." Turn the checkable subset of an agent's change summary — especially the no-failing-test facts (config, signatures, constants, references) — into deterministic git
.warrantreceipts that are born-verifiable now (catches "phantom changes," ~45% of message-code inconsistencies — arXiv 2601.04886) and REVOKE on later drift, token-free. Primary user: solo Claude Code power user; channel: a final-messageclaims.jsonconvention + the GitHub Action. Secondary: PR-summary rot (B) + executable-docs drift (E), same mechanism. Rejected F/G/H.Killer demo (proven first-hand)
DEMO_SCRIPT_BEST_USE_CASE.md: cleanpip install→ seal an agent change-note's claims on python-dotenv → flipoverride: bool = False → True→revalidate→ BROKEN (signature_mismatch: default of 'override': 'True' != 'False') → REVOKED, exit 4. No tokens at check time.Deliverables
BEST_USE_CASE_2026_06_27.md,USE_CASE_DECISION_MATRIX_2026_06_27.md,DEMO_SCRIPT_BEST_USE_CASE.md,CLAUDE_CODE_DORIAN_WORKFLOW.md,POSITIONING_2026_06_27.md.Honesty
Checkable-subset only (not the whole summary); not a sandbox/LLM-judge/SaaS; trigger-vs-truth preserved; unsigned-warrant + authoring-friction limits disclosed. The judge verified 4 load-bearing citations as real and flagged 2 citation fixes (curl "Feb 2026 shutdown" overreach; changelog date) — both fixed.
Dogfood
docs/changes/best-use-case-discovery.mdsealed under--strength-gate=fail(6/6): v1.2.0, zero-dep core, the CLIrevalidatecommand, and the SECURITY_BOUNDARY not-a-sandbox boundary — all warranted. Docs-only; no code/grammar/security-posture change.Summary by CodeRabbit