A documentation rule rejects vague headings at 60% confidence. Replacing them with Installation and Check a file makes the check pass.

Perch flagged “Getting started on your journey” at 60% confidence. Changing it to “Installation” and replacing a second vague heading cleared the finding. The captured run includes both documents and their results.

Add the heading rule

Save docs-headings-name-things in perch.yaml to check Markdown under docs/:

- name: docs-headings-name-things
  where: "docs/**/*.md"
  ensure: >-
    Read the first six headings. Each names a task or a topic.
    Vague narrative headings such as "What we learned" or
    "One issue, opened up" break this rule.

Run the rule after an edit. perch check reads the current file, including uncommitted changes:

perch check docs/install.md --rules docs-headings-name-things

Checking the original document produced exit 3. With the two headings corrected, the September 20 command exited 0 and printed:

docs/install.md:1
1 check, nothing to report.

The body and rule were unchanged. The full capture contains both documents and both checks; the GIF shortens the waits. Fresh model calls can return different scores.

Put the check in the agent’s instructions

Add this to the project’s agent instructions:

After editing Markdown under docs/, run:
  perch check <changed-file> --rules docs-headings-name-things
Inspect any findings and fix the passage before finishing.

Exit 3 means a finding. Exit 1 or 2 means the check could not complete. Add rules for repeated problems as they appear: filler paragraphs, misleading comments, or command examples without output. The documentation examples include those rules.

Keep each rule small enough to judge

“Every sentence is short” was a poor rule for a whole page. A deliberately bad version full of 34-word sentences scored 92%; the clean version scored 88%. It barely distinguished them.

The repository’s development notes record this comparison. Across ten pages, broad style rules also scored longer pages more harshly.

Restrict the question to a passage: the first four paragraphs, the first six headings, or the first command example. That gives the model a consistent amount of text to judge.

Test the rule on both versions

Keep the page fixed and change only the passage you are checking. Run the rule once on a known violation and once on the correction.

If both get similar scores, rewrite the question or remove it. Raising the threshold or rerunning until it passes hides the problem. Review the finding and the text it points to.