Vale integration
Overview
Section titled “Overview”Vale is an open-source prose linter that enforces style rules across documentation. Promptless lints the prose it writes with Vale and fixes style violations before they reach your review queue. Suggestions then match your style guide from the start, with less back-and-forth during review. Promptless also writes Vale rules from your style guidance and keeps them current.
Promptless runs Vale with its default rules even when your repository has no Vale config. This guide covers how to add your own Vale config to that run and how to choose which findings Promptless fixes.
Before you start
Section titled “Before you start”- An admin role in your Promptless organization, to set the Vale config path on the Configuration page.
Create a Vale config
Section titled “Create a Vale config”If you don’t have a Vale configuration yet, create a .vale.ini file in your docs repository root:
StylesPath = .vale/stylesMinAlertLevel = warning
[*.md]BasedOnStyles = ValeThis minimal config enables Vale’s built-in rules. For more comprehensive style enforcement, add external packages:
StylesPath = .vale/stylesMinAlertLevel = warning
Packages = Microsoft, write-good
[*.md]BasedOnStyles = Vale, Microsoft, write-goodSee the Vale documentation for detailed configuration options and available style packages.
Connect Vale to a doc collection
Section titled “Connect Vale to a doc collection”Promptless lints with your Vale config when it finds a Vale configuration file in your docs repository. To use a different config file, set the path yourself.
Automatic detection
Section titled “Automatic detection”During doc collection setup, Promptless scans the collection for a Vale configuration file matching any of the five names Vale recognizes: .vale, _vale, vale.ini, .vale.ini, or _vale.ini. When Promptless finds one, it lints the collection with that config. When the scan finds more than one candidate, Promptless uses the config in the shallowest directory within the collection’s scope. It breaks ties by the filename order above.
Set the config path manually
Section titled “Set the config path manually”-
On the Doc collections tab of the Configuration page, expand the doc collection.
-
Select More filters (optional).
-
In Vale config path, enter the repo-relative path to your Vale configuration file, such as
.vale.iniordocs/.vale.ini. -
Select Save changes.
In YAML mode, set the same path as the collection’s vale_config_path.
How Promptless runs Vale
Section titled “How Promptless runs Vale”Before it creates a suggestion, Promptless runs Vale on each prose file that it created or substantially edited, and fixes the findings. It does this for every doc collection, with or without a Vale config.
Promptless lints with these rules:
| Rules | When Promptless uses them |
|---|---|
| Promptless default rules | Always. The list is below this table. |
| Your organization’s rule set | When the rule set exists. Promptless writes it from your style guidance, or syncs it from your rules repository. See Vale rules. |
| The doc collection’s Vale config | When the collection has a Vale config. See Connect Vale to a doc collection. |
Your Vale config takes precedence. A rule that your config turns off, or sets a level for, keeps that setting.
Promptless default rules
| Rule | Level | What it flags |
|---|---|---|
House.Scaffolding | error | Sentences about the document itself, not its subject. |
Voices.Banned | error | Inflated words that need the sentence rewritten. |
Voices.BinaryContrast | error | A sentence that negates one idea to set up a grander one. |
Voices.ColonReveal | warning | A short phrase, a colon, then a reveal. |
Voices.InflatedWords | error | Inflated words that have a plain replacement. |
Voices.Puffery | error | Claims that something is important or impressive. |
Voices.Recap | error | Endings that restate what the text already said. |
Voices.SuperficialAnalysis | error | Trailing “-ing” clauses that add an unsupported claim. |
Voices.ThroatClearing | error | Openers that announce a point before they make it. |
Voices.WeakVerbs | error | Verb phrases that one verb can replace. |
Voices.Weasel | error | Appeals to unnamed sources. |
Direct.Hedging | error | Qualifiers that soften a claim. |
Direct.Length | error | Sentences over 25 words. |
Direct.Preamble | error | Lead-ins that delay the point. |
Moose.EmDash | error | Em dashes and double hyphens. |
To turn off a default rule for a doc collection, set it to NO in the collection’s Vale config, for example Direct.Length = NO.
When a doc collection has its own Vale config, Promptless also runs the same Vale command as your CI:
- It reads the Vale job in your GitHub Actions workflows or
.gitlab-ci.yml. If the job calls a wrapper script, it reads the script too. - It downloads the style packages that your config references, such as Microsoft or write-good, if they aren’t in your repository.
- It runs the command on the files it changed.
Vale lints prose only. It skips code blocks, commands, configuration, frontmatter, schemas, and tables.
To add a check that Promptless must run, write the command in PROMPTLESS.md in your Agent Knowledge Base. State that the command must pass. Promptless then pushes the branch only after the command passes.
If Vale fails in CI on a Promptless suggestion, see CI check and build fixes for GitHub or Pipeline failures for GitLab.
Severity handling
Section titled “Severity handling”Vale classifies violations into three severity levels:
| Severity | Behavior |
|---|---|
| error | Blocking. Promptless fixes these before creating the suggestion. |
| warning | Advisory. Promptless evaluates against your existing style and fixes when appropriate. |
| suggestion | Advisory. Promptless considers these but may preserve intentional style choices. |
How Promptless treats findings depends on whether your config sets MinAlertLevel.
When MinAlertLevel is set
Section titled “When MinAlertLevel is set”Setting MinAlertLevel sets the severity bar your docs hold to. Promptless fixes every finding Vale reports at or above that level, including warnings and suggestions. That mirrors what your Vale CI reports, so Promptless resolves findings you’d otherwise see as review comments before the suggestion reaches you.
For example, with MinAlertLevel = suggestion, Promptless fixes every error, warning, and suggestion Vale reports. Use this level when your CI fails on any Vale alert. To have Promptless fix fewer findings, raise the level, for example to warning or error.
When MinAlertLevel is unset
Section titled “When MinAlertLevel is unset”When your config doesn’t set MinAlertLevel, Promptless treats error-severity rules as hard constraints. It treats warning and suggestion rules as guidance and balances them against the established voice and conventions in your docs.
See also
Section titled “See also”- Vale rules, for how Promptless creates and maintains your organization’s rule set
- Audit and keep your docs healthy, for how Vale fits with Deep Analysis and Doc Detective
- Agent Knowledge Base, where Promptless records proposed Vale rules
- GitHub repos (docs as code), for every doc collection setting
- Doc Detective integration, to test the procedures your docs describe