# Habit rules

> Write your own rules for the words you lean on, test them with examples, and switch starter rules off.

Habit rules mark the words you lean on: hedges, intensifiers, filler and the like. They run on your computer when you check a note, and keep that note up to date as you write. They're free, and nothing leaves your vault.

Each rule is a small file in your rules folder (`Learning Editor/rules` unless you changed it in settings). A rule carries its own examples. When the rules load, each one runs its examples. If one fails, that rule is switched off and you get a notice saying which. Open [the panel](the-panel.md); the **Rules and profile** section lists the switched-off rules and why.

## Where rules come from

1. **Your rule files.** Anything in the rules folder, subfolders included.
2. **Your profile.** Each habit under "Habits to coach" becomes a rule, with its quoted phrases. "Automatic check" lines become a rule too.
3. **The starter pack.** Common English habits that come with the plugin: hedges, intensifiers, softeners, throat-clearing openers, wordy frames, vague words and vague openers.

If two rules share an id, the first one in that list wins. So a file named `hedges.md` replaces the starter pack's hedges rule.

To get copies of the starter rules to edit, select **Copy the starter habit rules** in the **Rules and profile** section of [the panel](the-panel.md). It never overwrites a file that's already there.

## What your profile protects

Some things are never flagged, by any rule:

- words and phrases under "Keep as written", and names from "House conventions"
- short items under "Voice to keep" and "Never fix" (a word or a short phrase, like *tho*)
- the quoted text of your rejected suggestions

A rule hit that touches any of these is left out.

## A rule file

A rule is a Markdown note with the rule in its frontmatter:

```markdown
---
id: actually
category: cuts
kind: cut
phrases:
  - actually
  - as a matter of fact
message: Usually filler. The sentence stands without it.
flags:
  - It actually worked.
  - As a matter of fact, we left.
allows:
  - The actual cost was higher.
---
Anything below the frontmatter is for you. If there's no `message`, the first paragraph here is used instead.
```

You can also write the same fields as a whole `.yml` or `.yaml` file.

## The fields

| Field | What it does |
|---|---|
| `id` | A short name, unique among your rules. Defaults to the file name. |
| `category` | Which group it shows in: `cuts`, `line`, `clarity`, `voice` or `mechanics`. Defaults to `cuts`. |
| `kind` | `cut` (the words can come out), `replace` (swap in `suggestion`) or `flag` (just a note). Defaults to `flag`. |
| `phrases` | Words or phrases to find. Matching ignores case, treats ' and ’ alike, and only matches whole words. |
| `regex` | A JavaScript regular expression, for what phrases can't say. Ignores case unless you add `case: sensitive`. `^` means the start of a line. |
| `message` | Why it's marked, in a few plain words. Shown on the card. |
| `suggestion` | What to write instead, for `replace` rules. A capital is added when the hit starts with one. |
| `flags` | Examples that must be marked. At least one is required. |
| `allows` | Examples that must not be marked. |
| `off` | `true` switches the rule off. Use it to turn off a starter rule or a profile habit by its id (profile habits have ids like `profile-hedges`). |

A rule needs `phrases` or `regex` (or both), a `message`, and at least one `flags` example.

## How a hit is shown

- A `cut` hit is offered as a cut: the phrase and the word next to it, with the phrase taken out ("really good" becomes "good"; at the start of a sentence the next word gets a capital). If there's no clean cut, it's shown as a note instead. A cut never adds words.
- A `replace` hit offers the suggestion.
- A `flag` hit is a note with the message.

Rules skip what isn't your prose: frontmatter, headings, block quotes, code, comments, link targets and embeds.

## Other local checks

Alongside your rules, the habits check also notes, in the Line group:

- **Close repeats:** a word of five letters or more that comes back within about 40 words. The later uses are marked.
- **Leaned-on words:** a content word you use six times or more in the note. The first use is marked, with the count.
- **Very long sentences:** longer than 35 words, and much longer than your other sentences in the same note (more than two standard deviations above their average).
- **Sticky sentences:** a sentence of 15 words or more where at least 60% are glue words, the small words like *of*, *the*, *it* and *that* that hold a sentence together without carrying its meaning. Only the three stickiest in a note are marked, and a sentence already marked as very long isn't marked again.

## Habit rate

The habit rate is how many rule hits there are per 100 words of your prose. The **Progress** section of [the panel](the-panel.md) shows it for the note you're on, next to your average. It's a count, not a grade.

The rate can be written to the note's frontmatter as `habit_rate`, so you can follow it across posts. That's off unless you turn it on, because it changes the file: select **Write habit rate to this note** in the panel, or switch on **Write habit rate to notes** in [Settings](settings.md). See [The panel](the-panel.md).