cot-lint
English | 中文
Lint your repo for chain-of-thought leakage — the session-transcript residue AI assistants leave in docs, comments, and JSDoc.
Your coding agent writes great code and leaks its thinking everywhere around it:
- // This PR adds a retry loop (decision 7) so the diff stays reviewable.
- // The manager used to serialize writes itself; it no longer does after v1.
- // The cast is safe — it simply narrows the union. Probably fine for now.
+ // Retries transient provider failures up to 3 times with jittered backoff.
+ // The shared coordinator serializes writes per session.
+ // The cast narrows a union already validated at the loader boundary.
None of the left column is wrong about the code. It is wrong about its reader: it argues with a reviewer who has left, cites a design session nobody can open, and narrates a change instead of stating behavior.
The one test
Could a reader at HEAD — with no access to any session transcript, PR thread, or uncommitted draft — resolve every reference and verify every claim?
If no, that passage is chain-of-thought leakage. cot-lint finds it.
Quick start
DeepSeek Harness — install the cot-trim fixing skill as a plugin:
dsh plugin add cot-lint
Any repo or CI — zero dependencies, Node ≥ 20:
npx cot-lint # scan the repo (Markdown and prose files)
npx cot-lint --json # machine-readable findings for CI or agents
npx cot-lint --ext ts,py # also scan source files line-by-line
npx cot-lint --hidden # descend into dot-directories such as .agents/
Exit codes: 0 clean · 1 findings · 2 usage error — drop it straight into CI.
What it detects
| Class | Example |
|---|---|
| dead design-session citation | (decision 7), design §4.7, phase tokens W3/T4, 设计稿 |
| stack/PR vantage | "this PR adds…", "a later PR in this stack" |
| change narration / version stamps | "used to", "no longer", "the old X", "the v1 refactor", "today", 旧版/不再 |
| review choreography | "Rejected in review:", "the reviewer confirmed", 上一轮评审 |
| reviewer-addressed justification | "the cast is safe — it simply…" |
| control-flow narration | "first we X, then we Y", "as you can see" |
| hedge / planning residue | "probably fine for now", "should be enough" |
| authoring-language slip | untranslated working-language fragments in the other language |
English and Chinese batteries are both built in.
What it deliberately does not flag
The keep-rules are half the tool. A zero-treatment linter that deletes RFC 9110 §10.1.5, a load-bearing TODO(alice):, or "the old connection drains before the new one accepts" (runtime lifecycle, not change history) does more damage than the leakage. So cot-lint mechanically exempts:
- issue references and marked
TODO/FIXME/XXXdeferrals, §-references on lines that cite an external standard such as an RFC,- lines carrying a
cot-lint-ignoresuppression — keep the reason next to it.
Batteries over-match by design. Every finding is a candidate, not a verdict; the keep-rules and rewrite method decide what survives.
Fixing, not just finding
The repo ships cot-trim, an agent skill that pairs with the CLI: it runs cot-lint --json, judges every hit against the one test, enumerates the passage's propositions before deleting anything, and fixes owner-first (generated files via their source, model-visible strings via their owning snapshot).
Install it where your agent looks for skills:
- DeepSeek Harness:
dsh plugin add cot-lint(orgithub:YuanyuanMa03/cot-lint) — thecot-trimskill loads through the plugin's skill provider. - Claude Code / generic agents: copy
skills/cot-trim/into your skills directory (~/.claude/skills/,.agents/skills/, or wherever your agent looks).
How this differs from "AI slop" style linters
Style-slop detectors flag prose that sounds like AI (word choices, em-dash habits). cot-lint flags prose whose vantage is the authoring session — references and narration that only make sense if you were there. Human-written docs can leak (copy-pasted PR descriptions do); AI-written docs can be clean. Different failure class, different tool.
Origin
The taxonomy, keep-rules, and battery approach are distilled from the engineering standards of DeepSeek Harness (MIT) — specifically its prose-hygiene practice for agent-written repositories — generalized here to work with any repo and any coding agent. See their CONTRIBUTING.md for the project's stance on community ecosystem work.
No comments yet. Be the first to write one.