Skip to content

For the complete documentation index, see llms.txt.

Vale rules

Vale is an open-source linter for prose. It checks text against rules the way a code linter checks code. Each rule is a YAML file, and Vale reports the same finding every time it runs. Many style guide rules can be Vale rules, such as terminology, capitalization, banned phrases, and sentence length.

Promptless writes Vale rules for you from your existing style guide. It keeps them as one rule set for your organization and lints every doc collection with it. This page covers how the rule set gets created, where it lives, and how it changes.

For how Promptless runs Vale on a suggestion, see Vale integration.

Your situationHow the rule set helps
Reviewers enforce your style guide by hand.Promptless writes Vale rules from your style guide. Vale then checks every suggestion, so reviewers stop checking those rules by hand.
Reviewers repeat the same style comment on suggestions.Promptless adds a rule for the preference, so later suggestions follow it before they reach review.
Your doc collections follow different conventions.One rule set applies to every doc collection in your organization.
Your organization already keeps its Vale rules in a Git repository.Promptless uses that repository as the source of the rule set and proposes its rule changes there for review.

Your style guide states a rule in prose:

Write “Acme CLI”. Don’t write “Acme cli” or “acme-cli”.

Promptless writes the Vale rule that checks it:

styles/StyleGuide/Terms.yml
extends: substitution
message: "Use '%s' instead of '%s'."
level: error
swap:
'Acme cli|acme-cli': Acme CLI

Vale then reports each place where a page breaks the rule:

docs/install.md
3:1 error Use 'Acme CLI' instead of 'Acme cli'. StyleGuide.Terms

Some style guide rules need judgment, such as a rule about tone. Promptless keeps those in your style guide and applies them as it writes.

During your pilot, the Promptless team works with your technical writers to turn your style guidance into Vale rules. Share your style guide and your Vale configuration, if you have one, before the pilot starts.

Promptless also writes rules on its own. When it analyzes a doc collection, it reads the collection’s style guidance and writes Vale rules from it.

The source of a rule sets its severity:

SourceSeverity
A rule your style guide stateserror or warning
A strong convention observed across your docssuggestion

To enforce an observed convention, add it to your style guide. Promptless then raises the rule to error or warning.

Promptless records the rule set under style/rules/ in your Agent Knowledge Base.

If your organization keeps its Vale rules in a Git repository, add the repository as a doc collection and set it as the rules collection:

style:
rules_collection: acme/style-rules

Promptless then syncs the rule set from that repository before each update. When it writes or changes a rule, it proposes the change to the repository as a suggestion.

Without a rules collection, Promptless proposes the rules to your documentation repository as a suggestion when it can place them there:

  • When the repository has a Vale configuration, the suggestion adds the rules to it.
  • When the repository has no Vale configuration, the suggestion can add one.

Promptless checks each rule against the Vale version your CI pins. When a rule needs a newer version, the suggestion raises your pin or rewrites the rule for the pinned version.

Promptless updates the rule set when your style guidance changes:

  • You give feedback. Promptless adds the style preferences it learns from your feedback to style/client_style_guide.md in your Agent Knowledge Base. It then writes or extends the Vale rules that enforce them.
  • You change your style guide. Promptless updates the rules that came from the changed guidance.
  • A rule flags correct text. Promptless narrows the rule.

A new or changed rule takes effect when Promptless writes it to your Agent Knowledge Base. Promptless lints its next suggestion with the rule. Promptless also proposes the change to your repository as a suggestion. See Where the rules live.