# snifftest

Adopt this skill: https://proskills.md/skills/other/danrwilloughby-snifftest-skills-snifftest

Page: https://proskills.md/skills/other/danrwilloughby-snifftest-skills-snifftest
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/snifftest/SKILL.md
size: 3969
upstream: https://github.com/danrwilloughby/snifftest/blob/main/skills/snifftest/SKILL.md

````text
---
name: snifftest
license: MIT
description: >
  Check a draft against the writer's house rules with the Sniff Test linter.
  Use when the user says /snifftest, hands you a Markdown or text file and asks
  whether it passes, asks which house rules a draft trips, or asks for a style
  or prose check on something they wrote. Reports the rule, the line and how
  sure the checker is, so the prose can be fixed rather than argued about.
user-invocable: true
---

# Sniff Test

A prose linter. It reads Markdown and plain text files, checks them against a
YAML ruleset, and prints one line per flag.

There are two kinds of rule and they behave differently.

**Countable rules** are regular expressions. Dash counts, banned words,
sentence rhythm, anything a computer can decide exactly. They run on the
machine, cost nothing, and send nothing anywhere. Run them whenever you like.

**Judgment rules** need something read rather than counted: a line that
undercuts its own claim, a cost stated without a price, a closing sentence that
only restates. Deciding those means sending the text to a model, so they only
run when the user has already agreed to it on this machine, or agrees now.

## Running it

Both passes go through the script in this skill's folder. It pins the version
of the tool it fetches and never answers the sending question on your behalf.

The free pass, which is the default and the one to reach for first:

```sh
sh "<skill-dir>/scripts/run.sh" path/to/draft.md
```

The judgment pass, only when the user has asked for it:

```sh
sh "<skill-dir>/scripts/run.sh" --judge path/to/draft.md
```

Directories work in place of files. Several paths work too.

Check the file the user asked about and nothing else. A file they did not name
is not yours to send.

## Rules about the judgment pass

Run the free pass as often as it is useful. It is local and free.

The judgment pass sends the draft off the machine, so it is the user's call and
not yours:

- The user has to have said yes. That is either a yes stored from an earlier
  run on this machine, or a yes in this conversation.
- Never talk them into it and never answer for them. Do not add flags to the
  command that skip the question, and do not put an answer into the
  environment. The script and the tool handle consent between them.
- If the tool exits with code 3, consent is missing and nothing was sent. Say
  so plainly, say what running the judgment rules would send, and let the user
  decide.
- The key the judgment rules use is read from the environment by the tool
  itself. Never read it, never print it, never put it in a command or a file.

## Reading the output

A flag is one line:

```
path:line rule score message
```

`rule` is the rule id from the ruleset. `score` is between 0 and 1, and it is
how sure the checker is rather than how bad the problem is. A countable rule
always scores 1.00. Judgment rules count as flags at or above the threshold,
0.7 unless the ruleset or the command says otherwise.

A line that reads `skipped, not text.` means the file was binary or not UTF-8.
Nothing was checked and nothing was sent.

Exit codes: 0 clean, 1 at least one flag, 2 the tool could not do its job, 3
the judgment rules need an answer before anything is sent.

`snifftest rules` prints the ruleset in force and where it came from, which is
the quickest way to answer "why did that flag".

## What to do with a flag

Fix the prose. A flag is a sentence to rewrite, not a rule to turn off.

Show the user the flagged line, say which rule it trips in plain words, and
offer a rewrite. Then rerun the check on the edited file, because a rewrite can
trip a different rule.

If the user decides a rule is wrong for their writing, the answer is to edit
the rule in their `.snifftest.yaml`, not to work around it in the draft. Ask
before changing their ruleset.

A score near the threshold is a judgment call, not a verdict. Say so rather
than rewriting a line the user likes.
````

## File: README.md
upstream: https://github.com/danrwilloughby/snifftest/blob/main/README.md

````text
<p align="center">
  <img src="assets/nose/nose.gif" alt="A pencil sketch of a nose in profile, sniffing twice and then approving" width="200">
</p>

# Sniff Test

Does the draft pass the sniff test?

Sniff Test reads Markdown and plain text and checks it against your house
rules. It prints one line per flag with the file, the line, the rule that
tripped and how sure it is.

There are two kinds of rule. **Countable rules** are regular expressions.
Long dashes, a paragraph with three colons, a banned word, every sentence the
same length. They run on your machine, cost nothing and send nothing anywhere.
**Judgment rules** need something read rather than counted. A closing sentence
that only restates the paragraph, a claim hedged three times, a line that talks
the reader out of the offer. For those it sends one paragraph at a time to a
small hosted judgment model and gets back one probability per rule. It only
does that after you have said yes.

Two things it is not. There is no general model in the loop; the judgment
model returns one probability per question and nothing else. And it will not
rewrite your text. A flag is a sentence for you to fix.

```sh
npm install --global snifftest
snifftest check --dry-run draft.md
```

That runs the countable rules and nothing leaves your machine. To run the
judgment rules too, put a TypeSafe key in `TYPESAFE_API_KEY` and drop
`--dry-run`. The first time, it prints exactly what it is about to send and
where, and waits for your answer.

It exits 0 when nothing tripped, 1 when at least one rule did, 2 when the tool
could not do its job, and 3 when the judgment rules needed a yes and did not
get one.

The nose is the mascot. It is one hand-drawn SVG with six expressions, in
`assets/nose/`, and `snifftest serve` opens a local page where you type and the
nose reacts.

## Reading a flag

```
draft.md:14 dash_present 1.00 A long dash. Give the sentence a full stop instead.
draft.md:31 restating_closer 0.84 The last sentence says the paragraph again. End one sentence earlier.
```

The number is how sure the checker is, between 0 and 1, and it says nothing
about how bad the problem is. A countable rule always scores 1.00. A judgment
rule counts as a flag at or above the threshold, which is 0.7 unless the
ruleset or `--threshold` says otherwise. A reading between 0.4 and 0.6 is
reported as no judgment and never becomes a flag or a pass. That band exists
because the judgment model answers about 0.5 on text it cannot read, and a
flat middle number is the one failure that looks like a clean draft.

After a judgment run, `check` prints a usage line on stderr with the request
count, input tokens and estimated cost at the disclosed rate. The price has
no recorded published source, and the line says so. `--quiet` hides that line
without hiding flags or diagnostics. A dry run prints no usage line.

`--format json` prints the same flags for a machine, with every reading
including the ones under the threshold. `snifftest rules` prints the ruleset in
force and which file each rule came from, which is the quickest answer to "why
did that flag".

## The rules

The default ruleset ships in `rules/default.yaml`. Fifteen rules, and the file
itself is the documentation. Ten apply to most prose and five are conventions
of copy meant to sell.

| Rule | Kind | What it catches |
| --- | --- | --- |
| `dash_present` | countable | An en dash or an em dash. A hyphen is fine, and so is an en dash between numerals. |
| `colon_heavy` | countable | Three or more colons in one paragraph. URLs and clock times do not count. |
| `sentence_rhythm` | countable | Every sentence the same length, in paragraphs of four sentences and sixty words or more. |
| `slop_vocab` | countable | Twelve words that turn up far more often in generated text than in prose a person wrote. |
| `banned_words` | countable | Your own list. Empty until you fill it. |
| `not_x_but_y` | judgment | A sentence whose whole job is to swap one label for another. |
| `tricolon` | judgment | Three items for the cadence. |
| `stacked_hedging` | judgment | Two or more softeners on one claim. |
| `rhetorical_opener` | judgment | A paragraph that opens on a question nobody asked. |
| `restating_closer` | judgment | A last sentence that says the paragraph again. |
| `self_undercutting` | judgment, marketing | Copy that talks the reader out of the thing on offer. |
| `first_x_that` | judgment, marketing | A claim to be the first. |
| `naked_cost_figure` | judgment, marketing | A cost with no customer price and no alternative beside it. |
| `jobs_claim` | judgment, marketing | A claim about employment. |
| `pullquote_fragment` | judgment, marketing | A display quote with no verb. |

The five rules tagged `marketing` sit out an ordinary run. Ask for them on a
landing page with `--only marketing`, which runs those five and nothing else.
To run everything, write a project file that extends the default and sets
`off_by_default: []`.

Fenced code is dropped before either kind of rule sees it. Headings, tables,
front matter, link definitions and HTML comments are never sent to the
judgment rules, and the countable rules only read the ones a rule names.

### Writing your own

A `.snifftest.yaml` in your project root is picked up on every run. It can
extend the default ruleset and change the rules it disagrees with, matched by
id, so a house that wants five colons instead of three writes one rule and
inherits the other fourteen.

```yaml
version: 1
extends: default
threshold: 0.7

rules:
  # A countable rule of your own is a pattern and a message.
  - id: no_utilize
    kind: regex
    pattern: "\\butili[sz]e"
    flags: i
    message: "Use. The word is use."

  # Override a shipped rule by reusing its id.
  - id: colon_heavy
    kind: regex
    builtin: colon_count
    min: 5
    message: "Five colons in one paragraph."

  # A judgment rule is a description, its near misses, and two criteria.
  - id: passive_apology
    kind: judgment
    what: |
      A sentence that apologises for the document itself: for its length,
      its lateness, or the writer's lack of expertise.
    not_for: |
      An apology to a person for a thing that happened.
      A stated limit of scope.
    examples:
      - "Sorry this is so long."
      - "I am no expert, but here goes."
    criteria:
      true: "At least one sentence apologises for the document or the writer."
      false: "No sentence apologises for the document or the writer."
    message: "The draft is apologising for itself. Cut the line."
```

A countable rule names either a `builtin` or a `pattern`, never both. The
built-ins are `dash_present`, `colon_count`, `sentence_rhythm`, `slop_vocab`
and `banned_words`, and each takes the tuning keys the default file shows. A
rule may carry `tags`, and a countable rule may name the kinds of block it
applies to with `chunks`. A judgment rule's `not_for` is what keeps it honest.
A rule with a `what` and no `not_for` will flag things you did not mean.

A pattern with a nested quantifier is refused when the ruleset loads, and
every pattern runs against a capped slice of text. Neither is a proof that a
pattern cannot run for a long time. See `SECURITY.md`.

To propose a rule for the shipped set, open a rule proposal issue.
`CONTRIBUTING.md` says what one needs.

## Consent, and what leaves the machine

Nothing is sent before the answer to one question is yes. The countable rules
run first, on your machine, whatever happens next. Then, if the ruleset has
judgment rules and you did not pass `--dry-run`, the checker looks for a key in
`TYPESAFE_API_KEY`. Without one it prints the countable verdict, says the
judgment rules could not run, and exits 2. With one, it prints this and waits:

```
Sniff Test is about to use the judgment rules, which run on a model.

  What leaves this machine: one paragraph of your text at a time, from 3 files,
    together with the wording of these rules: not_x_but_y, tricolon, stacked_hedging, rhet
````
