convez.ai
PluginEscrita & ConteúdoIntermediário
tbhb

Vale AI Tells

tbhb/vale-ai-tells

Detecta e remove padrões de escrita típicos de IA em docs técnicas

Ver no GitHub
BomPluginScore · de 0 a 100

Plugin para Vale que detecta padrões linguísticos típicos de textos gerados por IA em documentação técnica. Fornece regras específicas para prosa e mensagens de commit, ajudando a identificar e limpar vocabulário, estruturas de frase e tells comuns de IA para melhorar a qualidade e autenticidade do conteúdo.

Instalação

$npx convez-ai tbhb/vale-ai-tells

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
135
Forks
13
Acompanhando
1
Saúde
42%
Último commit
há 2 semanas
Versão
v1.37.0
Issues abertas
14
Contribuidores
1

Casos de uso

  • Limpeza de documentação técnica assistida por IA
  • Validação de qualidade em mensagens de commit
  • Identificação de vocabulário genérico e estruturas de frase artificiais

Veredito

Ferramenta prática e bem direcionada para documentação técnica, com regras específicas comprovadas por pesquisa 2024-2025. Honesto em seus objetivos: melhorar clareza sem pretender mascarar conteúdo gerado por IA como humano.

README

A tradução para o português deste README ainda está na fila.

vale-ai-tells

A Vale package for detecting linguistic patterns commonly associated with AI-generated prose. Based on 2024-2025 research into vocabulary fingerprints and structural tells.

This package targets technical documentation, where clarity and directness matter more than style. Less useful for creative writing, marketing copy, or other contexts where some of these patterns may represent intentional choices.

[!NOTE] The author created this package to help clean up AI-assisted technical documentation, not to disguise AI-generated content as human-written.

linted with vale-ai-tells

Installation

Add the package to your .vale.ini:

StylesPath = styles
MinAlertLevel = suggestion

Packages = https://github.com/tbhb/vale-ai-tells/releases/download/v1.19.0/ai-tells.zip, \
  https://github.com/tbhb/vale-ai-tells/releases/download/v1.19.0/ai-tells-commits.zip

[*.md]
BasedOnStyles = ai-tells

Then run:

vale sync

Linting commit messages

AI-generated commit messages carry the same fingerprints as AI-generated prose, plus a few tells of their own: self-referential preambles like "This commit adds\u2026," trailing justification clauses like "\u2026ensuring consistency," buzzword adjective combos like "comprehensive tests" and "robust error handling," and gitmoji patterns.

The ai-tells-commits style provides 13 rules purpose-built for commit messages, separate from the prose rules so you can opt in without pulling them into your docs.

Commit message rules

RuleDescription
CommitSelfReferenceSelf-narrating preambles: "This commit adds...," "This PR introduces...," "In this change...," "These changes ensure...," etc.
CommitTrailingJustificationTrailing clauses that restate the obvious: "...ensuring consistency," "...improving readability," "...which allows for," "for better maintainability," etc.
CommitBuzzwordsVague adjective+noun combos: "comprehensive tests," "robust error handling," "proper validation," "various fixes," "relevant components," "necessary changes," etc.
CommitHedgingInappropriate uncertainty for changes already made: "This should fix...," "This may help...," "seems to resolve...," etc.
CommitEmojiSystematic gitmoji prefixes (✨🐛♻️📝⚡✅🔧🔥🚀 etc.) — emoji commit adoption has jumped from ~25% to ~75% of organizations, driven almost entirely by AI tools.
CommitOverexplanationFiller that pads without informing: "As part of this change...," "The purpose of this commit...," "Summary of changes," "The following changes were made," etc.
CommitTestEnumerationScoreboard-style test reporting: "All 47 tests passing," "Tests: 12 passed, 0 failed," "Coverage: 87%," "100% test coverage," etc. Link the CI run instead.
CommitAttributionAgent marketing trailers: robot-emoji "Generated with" lines, "Co-Authored-By: Claude/Copilot/Cursor," "noreply@anthropic.com," etc. Use kernel-style Assisted-by: AGENT:VERSION instead.
CommitPastTensePast-tense or present-participle verbs on the subject line: "Added X," "Fixed Y," "Refactoring Z." Use imperative mood.
CommitChangelogStyleKeep-a-Changelog-style headings inside a single commit body: ## Added, ### Fixed, ### Breaking Changes, etc. CHANGELOG.md is the place for that format.
CommitMarketingAdjectivesMarketing intensifiers: "production-ready," "enterprise-grade," "mission-critical," "battle-tested," "bulletproof," etc. State what changed and why.
CommitUnquantifiedClaimsUnquantified performance, size, or speed claims: "significantly faster," "much smaller," "blazingly fast," etc. Currently at warning level. Back claims with numbers.
CommitFileListingThree or more consecutive bullets that look like file paths. Currently at warning level. The diff already shows files changed; describe what changed about the code.

Setup

Add a [formats] section and a dedicated section for the commit message file to your .vale.ini:

[formats]
COMMIT_EDITMSG = md

[{COMMIT_EDITMSG,.git/COMMIT_EDITMSG}]
BasedOnStyles = ai-tells, ai-tells-commits

The glob covers both how pre-commit passes the path and direct Vale invocations. Use both styles together: ai-tells catches general vocabulary and structural tells, ai-tells-commits catches commit-specific patterns.

Add the commit-msg hook to your .pre-commit-config.yaml:

  - repo: https://github.com/errata-ai/vale
    rev: 27593b0e0e7eb8f0c2b7fae0d93fa1cfaabceb2f # v3.13.0
    hooks:
      - id: vale
      - id: vale
        name: vale (commit message)
        stages: [commit-msg]
        args: [--ext=.md]

Install the hook:

prek install --hook-type commit-msg

Example

A blocked commit:

$ git commit -m "This commit leverages a comprehensive solution to seamlessly enhance the functionality"

vale (commit message)....................................................Failed
- hook id: vale
- exit code: 1

 .git/COMMIT_EDITMSG
 1:1   error  AI commit tell: 'This commit'. Commit messages shouldn't     ai-tells-commits.CommitSelfReference
              narrate themselves—just state what you did and why.
 1:13  error  AI vocabulary: 'leverages'. Replace with a more specific     ai-tells.OverusedVocabulary
              or common word.
 1:24  error  AI commit tell: 'comprehensive solution'. This vague         ai-tells-commits.CommitBuzzwords
              buzzword combo is a hallmark of AI-generated commits.
 1:48  error  AI vocabulary: 'seamlessly'. Replace with a more specific    ai-tells.OverusedVocabulary
              or common word.

Suppressing noisy rules

Some prose rules matter less for commit messages. If they generate noise, suppress them in your .vale.ini:

[{COMMIT_EDITMSG,.git/COMMIT_EDITMSG}]
BasedOnStyles = ai-tells, ai-tells-commits
ai-tells.SycophancyMarkers = NO
ai-tells.ClosingPleasantries = NO

Rules included

This package contains 60 rule files covering different categories of AI tells. All rules default to error level.

RuleDescription
AbsoluteAssertionsAI overconfidence: "the only way to," "the only real solution," "make no mistake," "there is no denying," "above all else," etc. Verify the claim or soften it.
AIAdjectiveNounPairsAI adjective immediately preceding a noun: "holistic approach," "seamless integration," "transformative impact," etc. Currently at warning level.
AICompoundPhrasesCompound phrases: "rich tapestry," "intricate interplay," "paradigm shift," "double-edged sword," "moving the needle," "unlocks new," etc.
AnnouncementHeadingsHeadings that narrate content rather than being it: "What You'll Learn," "What We'll Cover," "What to Expect," "Here's What You'll Get," etc.
AnthropomorphicJustificationTreating abstractions like employees: "earns its keep," "does the heavy lifting," "pulls its weight," "pays for itself," "speaks for itself," "load-bearing," "does the real work," etc.
AffirmativeFormulasRevelation patterns: "Here's the thing," "And that's the beauty of it," "Let that sink in," etc.
ClosingPleasantriesSign-off language: "I hope this helps," "Feel free to ask," "Don't hesitate to reach out," etc.
ColloquialAssessmentsKnowing-tone verdicts: "the joke lands," "really lands," "X is the move," "that's the move," "what really matters," "all that matters," etc.
ColonUsageA capitalized word after a colon, the "Label: Sentence" construction ("The takeaway: Always test."). Replaces Google.Colons, which also lints heading text and flags the title half of "Appendix A: Glossary"; headings are exempt here. Acronyms, the pronoun "I," quotations, and clock times stay clean. Vale strips markup before matching, so run-in bold labels ("Example: Like this.") still flag; disable the rule where that convention is established.
ConclusionMarkersFormulaic conclusions: "In conclusion," "Ultimately," "At the end of the day," etc.
ContrastiveFormulasRhetorical contrasts: "It's not just X; it's Y," "These aren't X. They're Y," "This doesn't mean X. It means Y," "The real question isn't X; it's Y," "Not only X but also Y," etc.
ContrastiveNegationTelegraphic negation cadence that replaces the "not X; it's Y" formula once it gets flagged: stacked "no setup, no config, no hassle" and the single clause-final fragment "cleartext repo names, no k-anonymity gate." Aggressive; it can fire on "coffee, no sugar," so disable it for terse spec lists.
DefensiveHedgesPreemptive concessions: "This may seem X, but..." "Admittedly, X, but..." "At first glance," etc.
DespiteChallengesThe "despite challenges" dismissal formula: "despite these challenges," "while challenges remain," "challenges notwithstanding," etc.
EmDashUsageEm-dashes, which AI uses excessively
EmphaticCopulaItalicized copula verbs and determiners for manufactured profundity
EmptyPaddingEmpty modifiers before a noun the noun does not need: "named stakeholders," "various stakeholders," "respective roles," "given task," "particular concerns," etc. Sequence-based (modifier plus noun), so it casts a wide net and flags literal uses too ("named pipe," "various reasons," "a certain amount"). Deliberately broad; suppress per-section or disable where the literal sense is common.
EmptyPaddingStackedThe same empty modifiers with an adjective ahead of the noun: "named operational support," "certain strategic concerns," "various regional teams," etc. A three-token companion to EmptyPadding for the modifier-adjective-noun shape, since Vale sequences cannot make the adjective slot optional. Same breadth and the same suppression advice.
ExplainerHeadingsTutorial-blog heading clichés: "Deep Dive," "Under the Hood," "Demystifying X," "Why It Matters," "A Closer Look," etc.
FalseBalanceEvasive "both sides" language: "both sides present valid points," "nuanced approach," etc.
FalseExclusivityFalse insider drama: "nobody talks about," "what most people miss," "the dirty secret," "the elephant in the room," etc.
FigurativeLands"Lands" as an overused arrival verb: "the request lands on the node," "the PR lands in main," "where the idea lands." Exempts common literal landers (a plane, a bird, a probe); rare ones fire, so disable the rule for aviation or nature writing.
FillerPhrasesPadding and performative sincerity: "a wide range of," "in order to," "honestly," "to be perfectly honest," "the honest truth," etc.
FormalRegisterOverly formal vocabulary: "utilize," "facilitate," "commence," etc.
FormalTransitionsFormal transitions: "Moreover," "Furthermore," "What's more," "Case in point," etc.
GrowthMetaphorsThe startup-as-organism register: "incubate," "gestate," "nascent," "fledgling," "embryonic," "cultivate," "nurture," "in its infancy," plus scoped startup phrases ("minimum viable," "seed funding," "organic growth"). Disable for medical, nature, or agricultural writing.
HedgingPhrasesCompulsive hedging: "It's important to note that," "That being said," "Generally speaking," "As you might expect," etc.
ListIntroductionsAnnouncements of upcoming lists or summaries: "Below you'll find," "Here's a breakdown of," "Here's everything you need to know," "The following sections will," etc.
MarketingHeadingsPromotional-register heading clichés: "The Ultimate Guide," "Everything You Need to Know," "Mastering X," "Unlocking X," "The Power of X," "The Future of X," "Revolutionizing X," etc.
MetacommentaryThroat-clearing and self-commentary that narrates the text rather than adding content
MicDropShort dramatic sentences for manufactured emphasis in technical prose: "It matters." "Full stop." "And it shows." Contrastive fragments: "Dense, not cramped." Preference fragments: "Clarity over cleverness." Imperative mic-drops: "Trust the process." Categorical declarations: "Density is a feature."
MicDropHeadingsTagline-style headings: "Clarity, not cleverness," "Simple, then fast," "Speed over correctness," "X first, Y second," etc.
NarrativePivotsUnearned dramatic pivots: "something shifted," "everything changed," "that changed everything," "changed the game," "rewrote the playbook," "flipped the script," "it was a wake-up call," etc.
OpeningClichesAI-style openings: "In today's rapidly evolving landscape," "Without further ado," "Whether you're," etc.
OrganicConsequenceFalse inevitability: "emerges naturally," "a natural consequence," "follows naturally from," etc.
OverusedVocabularyWords with documented AI overuse: "delve," "comprehensive," "unprecedented," "sophisticated," "salient," "efficacy," "paramount," "cognizant," "camaraderie," "palpable," "fleeting," "amidst," "genuinely," "genuine," "supercharge," "unleash," "democratize," etc. Verb forms (leverage, harness, etc.) moved to OverusedVocabularyVerbs.
OverusedVocabularyVerbsVerb forms of AI vocabulary fingerprints: "leverage," "navigate," "showcase," "harness," "embark," "foster," "spearhead." Sequence-based for precision — noun forms such as "financial leverage" do not trigger.
ParallelStaccatoBack-to-back minimal sentences with parallel structure: "Engineers build. Managers ship." "Content carries the personality. Chrome doesn't." Solo two-word staccato: "Complexity scales."
ParticipialPaddingPresent participle (-ing) phrases appended for shallow analysis: "highlighting its importance," "reflecting broader trends," "underscoring its role," "solidifying its position," etc. The #1 discriminating feature in the PNAS study (527% of human rate).
PromotionalPufferyAd-copy and travel-brochure language: "nestled in," "vibrant community," "a beacon of," "renowned for its," "has emerged as a," "left an indelible mark," etc.
RedundantPrecautionRedundant-precaution idioms that signal over-engineering thinking: "belt and suspenders," "belt-and-suspenders."
ResonateOveruse"Resonate" as an overused reception verb: "resonates with audiences," "resonates deeply." Flagged broadly; the only literal sense is physics and acoustics, so disable the rule for physics or audio writing.
RestatementMarkersRedundant restatements: "In other words," "Simply put," "To be more specific," etc.
RhetoricalDevicesRhetorical question patterns: "Ask yourself:", "The test:", "When doing X, ask:" etc.
RhetoricalSelfAnswerSelf-posed rhetorical questions answered for dramatic effect: "The result/catch/worst part?" followed by an immediate answer.
SelfReferenceSelf-referential cross-references: "as mentioned above," "as noted earlier," "as we'll explore," etc.
SemicolonUsageSemicolons used as an em-dash substitute: a comma-free, clause-final continuation ("It does one thing; it does it well."). Exempts the legitimate uses, which carry a comma (lists with internal punctuation, "; however," joins, complex clauses). Google.Semicolons still warns on the rest.
SequencingMarkersFormulaic ordinal sequencing: "Firstly," "Secondly," "Thirdly," "The first takeaway," "The second benefit," etc.
ServesAsDodgeInflated copula replacements: "serves as a," "stands as the," "represents a pivotal," "boasts a vibrant," etc. Use "is" or "are" instead.
ShipOveruse"Ship" as an AI overuse fingerprint: the release verb ("ship it," "ship fast," "ship the feature") and the maritime clichés ("run a tight ship," "the ship has sailed"). Deliberately broad with no exemptions, so the logistics verb and the vessel noun are flagged too. Disable the rule for maritime or logistics writing.
StackedAnaphoraStacked repetition for emphasis: "No X. No Y. No Z." "It's X. It's Y. It's Z." etc.
StrategyBuzzwordsStrategy-deck buzzword metaphors: "growth flywheel," "competitive moat," "north star metric," "network effects," "first-mover advantage," "land grab." Each is scoped to the figurative shape, so the engine's flywheel, a castle's moat, and the real North Star stay clean.
StructureAnnouncementsNarrating upcoming structure: "key takeaway," "quick recap," "to recap," "quick summary," "to put it plainly," "to put this in perspective," etc.
SycophancyMarkersFlattering phrases: "Great question," "I'm happy to help," "You make an excellent point," etc.
UnpackExploreExplainer announcements: AI's habit of announcing what it is about to explain rather than just explaining it. Phrases beginning with "Let me" or "Let us" followed by unpack, break down, dive in, walk through, examine, explore, etc.
UrgencyInflationFalse urgency and importance assertions: "cannot be overstated," "more important than ever," "has never been more critical," "the stakes have never been higher," "at a critical juncture," "in an increasingly connected world," etc.
VagueAttributionsClaims attributed to unnamed authorities: "experts argue," "studies show that," "research suggests," "a growing body of evidence," etc.
VerbTricolonExactly-three parallel verb lists: "build, test, and deploy," "define, validate, and transform," etc.
VerbTricolonDensityMultiple verb tricolons in one paragraph — LLM prose clusters exactly-three enumerations.
WrapUpHeadingsClosing-flourish headings: "Final Thoughts," "Closing Thoughts," "Wrapping Up," "Putting It All Together," "The Big Picture," "The Bottom Line," "The Takeaway," etc.

What to write instead

Quick substitution reference for the most common patterns:

Instead ofWrite
delve intolook at, cover, examine
leverage (verb)use, apply, build on
utilizeuse
seamlessly(delete)
comprehensive(delete, or name what's included)
in order toto
Moreover / FurthermoreAlso, And, or start a new sentence
em-dashcomma, period, or parentheses
It's important to note that(delete — just state the point)
I hope this helps(delete)

Using with AI agents

Each error message gives AI agents, and humans alike, specific, usable guidance to fix issues immediately. Messages include:

  • A short prefix for quick identification: AI hedge:, AI filler:, and similar labels
  • The matched text
  • A concrete action: delete, rewrite, replace, or use a simpler word

Example workflow with an AI coding assistant:

You: Run `vale docs/` and fix any warnings or errors you find.

Agent: Running vale... Found 4 issues:

1. docs/intro.md:5 - AI opening: 'In today's rapidly evolving'.
   Start with your actual point instead of this generic lead-in.
2. docs/intro.md:12 - AI vocabulary: 'delve'.
   Replace with a more specific or common word.
3. docs/intro.md:12 - AI punctuation: em-dash detected.
   Use a comma, period, or parentheses instead.
4. docs/guide.md:8 - AI filler: 'in order to'.
   Delete this phrase—it adds no meaning.

Fixing these now...

[Agent edits the files, replacing generic phrases with specific content]

Running vale again... No issues found.

Customization

Disable specific rules:

[*.md]
BasedOnStyles = ai-tells
ai-tells.FormalTransitions = NO
ai-tells.EmDashUsage = NO

Change severity levels:

[*.md]
BasedOnStyles = ai-tells
ai-tells.HedgingPhrases = error

Early prevention with AI agent instructions

If you use an AI coding assistant, add instructions to your project's CLAUDE.md, AGENTS.md, or similar file to prevent Vale violations before they happen:

## Writing style

When writing or editing prose:

- Avoid AI vocabulary fingerprints: "delve," "tapestry," "multifaceted,"
  "leverage," "foster," "underscores," "comprehensive," "robust"
- Don't open with generic phrases like "In today's rapidly evolving..."
- Skip hedging ("It's important to note...") and filler ("in order to")
- Use commas or periods instead of em-dashes
- Cut sycophantic openers: "Great question!" "Absolutely!"
- Prefer simple words: "use" not "utilize," "help" not "facilitate"
- Start paragraphs with your actual point, not rhetorical wind-up

Limitations

This package catches lexical and phrasal patterns. It can't detect:

  • Sentence-length uniformity, or burstiness
  • Perplexity scores
  • Paragraph-length patterns
  • Semantic analysis
  • Model-specific stylometric signatures

Known patterns not covered

AI writing research documents these patterns, but they need analysis beyond Vale's token-matching capabilities:

  • Sentence-length uniformity: AI produces sentences of near-uniform length, roughly 27 words, while human writing varies widely. Requires statistical analysis across the document.
  • Paragraph-length uniformity: AI paragraphs tend toward uniform size, typically 3-5 sentences and 60-100 words each. Requires document-level measurement.
  • Dead metaphor repetition: AI latches onto a single metaphor and repeats it 5-10 times throughout a piece. Requires tracking metaphor usage across the document.
  • One-point dilution: A single argument restated 10 ways across thousands of words — circular repetition disguised as comprehensiveness. Requires semantic analysis.
  • Elegant variation: AI's repetition-penalty pushes it to substitute synonyms unnaturally, cycling through "protagonist," "key player," "eponymous character" instead of reusing a name. Requires NLP-level analysis.
  • Content duplication: Repeating entire sections or paragraphs verbatim within the same piece. Requires document-level diff analysis.
  • Unnecessary inline definitions: AI habitually inserts appositive definitions like "X, a [definition], does Y" even when the audience already knows the term. Too many false positives for token matching.
  • Invented concept labels: AI appends abstract problem-nouns like "paradox," "trap," "creep," and "divide" to domain words and treats them as established terms. Too many legitimate uses for token matching.
  • Noun-phrase + participial-phrase fragments: AI drops fragments built from a noun phrase and a trailing past-participle modifier ("The same set, applied identically by every client on every open.") as paragraph closers. Distinguishing them from legitimate appositive constructions requires syntactic parsing.
  • Adjective-led sentence fragments: AI ends paragraphs with adjective-led fragments that lack an explicit subject or verb ("Durable enough for coordination state, without the full-sync cost on every commit."). Without dependency parsing, regular expressions can't separate these from valid continuations of a prior sentence's subject.
  • Headless-infinitive openers: AI opens sections with a noun + infinitive-modifier fragment ("Threads to pull on in Claude Code before the surface hardens.") that reads as a section title posing as a sentence. Catching the structure requires distinguishing it from legitimate noun-phrase headings, which regular expressions can't do reliably. Some of the vocabulary that recurs in these fragments (thread-pulling metaphors, solidification metaphors) is now covered by AICompoundPhrases.
  • AI tells with inline-code subjects. Vale strips inline code (` code `) from prose before applying regular-expression rules, so patterns like the A X verbs ... A Y verbs ... parallel-mirror or No X, no Y. anaphora silently fail when the subject contains an identifier wrapped in backticks — common in technical documentation. Switching the rule to scope: raw would catch them but also fires on repetition inside code blocks and on documentation that quotes example patterns. The marginal coverage gain isn't worth the new FP sources.

For fuller detection, combine this package with statistical analysis tools.

Supplementing with AI agent instructions

Vale can't detect structural patterns like sentence uniformity or paragraph rhythm. If you use an AI coding assistant, add instructions to your project's CLAUDE.md, AGENTS.md, or similar file to cover what Vale misses:

## Writing style

When writing or editing prose, vary your structure:

- Mix sentence lengths: follow long explanations with short punchy statements
- Vary paragraph lengths—not every paragraph needs 3-4 sentences
- Avoid the "topic sentence, three supporting points, conclusion" formula
- Don't start consecutive paragraphs or sentences with the same word
- Skip the "In conclusion" wrapper—just end when you're done
- Let some points stand alone without hedging or qualifications
- Be willing to be direct, even blunt, rather than diplomatically balanced

This covers structural patterns that lexical analysis can't catch.

Sources

Based on academic research, practitioner analysis, and community-maintained catalogs of AI writing patterns:

Academic research

Pattern catalogs

Practitioner analysis

Commit message research

AI disclosure

Claude wrote the majority of rule definitions, documentation, and test cases in this repository. ChatGPT and Gemini generated text samples for cross-model validation. A human designed the rule categories, severity assignments, quality criteria, and the research-to-rule pipeline. A human validated every AI-generated rule against test documents containing known patterns.

The CITATION.cff lists the human author. It omits AI tools, consistent with Committee for Publication Ethics (COPE) guidance on AI and authorship.

Citation

If you use this package in research or want to cite it, see CITATION.cff for the citation metadata.

License

MIT

Ver o original no GitHub

Bom para

Relacionados