honesty

Honesty

Audit a codebase so every comment, docstring, and doc file tells the truth about the code — for the next AI agent (or human) who reads it before changing anything.

A comment is a promise about what the code does. When it drifts, it becomes worse than no comment: the next reader trusts it, builds a wrong mental model, and ships a mistake. And the next reader is increasingly an AI coding agent — it reads a docstring that says a function returns null, writes a dead null-guard against a function that actually throws, and skips the try/catch. The comment meant to help is the thing that makes it wrong.

Honesty finds those broken promises and either corrects them or flags them. It's a Claude Code plugin: one skill that audits a codebase module by module and tells you exactly which comments lie, which are missing, and which can be fixed automatically versus which need your eye.

How it works

scope → bundle → audit (one agent per module) → structured findings →
  disposition (auto-fix vs review) → apply + verify → review queue → roll

It checks every surface the code makes claims on — inline + block comments, docstrings/JSDoc, doc files (README, CLAUDE.md/AGENTS.md, ARCHITECTURE.md, DATABASE_SCHEMA.md), and config-file comments — against a tight rubric:

• inaccurate — contradicts the code (wrong condition, default, return, or API contract)
• stale — wrong counts/dates/enumerations, done-but-still-"TODO", "temporary" that's now permanent, superseded behaviour, broken cross-references
• misleading — builds a wrong mental model
• gap — non-obvious / load-bearing code with no comment
• unclear — too vague to help

It's deliberately high-signal — an all-sound module returns nothing, and that's a good result.

Auto-fix is gated, not eager

Confidence alone doesn't make a fix safe to apply — a confident edit to a contract docstring or to CLAUDE.md can mislead far beyond one line. Honesty auto-applies a finding only when it's high confidence AND a mechanical factual correction AND local in blast radius AND not a doc/config file. Everything else — rewrites, gap-fills, contract docstrings, every doc-file change — goes to a review queue with the suggested fix attached. New codebases default to findings-first; auto-fix is a knob you turn on once a calibration batch proves the signal.

What it is not

• Not a doc generator (pair it with one — honesty flags a stale ARCHITECTURE.md, the generator regenerates it).
• Not a comment-stripper — stale comments get corrected, not deleted; missing ones get added.
• Not a style linter, and it leaves user-facing strings alone (that's product behaviour, not developer truth).

One lane: are the claims the code makes about itself true, and present where they matter.

See docs/pattern.md for the methodology, the disposition gate, and the evidence from real runs (including a real bug found hiding behind a technically-true comment). The skill itself is in skills/honesty/SKILL.md; reusable audit prompt + findings schema are in templates/.

---

Part of a family of Claude Code plugins: fixer, perfection, walkabout.

MIT © Jeremy Dawes / Jezweb