Skip to content

P0012 narration

Rule: Docs and comments state facts, not how they were written.

Code P0012 (stable, never reused)
Id narration
Category prose
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small off
small-workspace off
medium off
big off
ai deny docs and comments state facts, not the conversation that produced them
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
phrases list of strings ["let me", "let's", "as requested", "as you asked", "as discussed", "now we", "now i", "first i", "first we", "then i", "next i", "next we", "i'll", "i've", "i will", "we'll", "here's", "here is the"] the narration phrases, matched as whole words, case-insensitive
files list of strings ["**/*.md"] globs of the Markdown files checked, relative to the root
skip list of strings [] globs of Markdown files left out
comments boolean true also check Rust comments

Why

Docs and comments describe the code as it is. Narration ("let me", "as requested", "first I", "now we") describes how the text came about: a conversation that the reader never saw. It is the mark of text pasted from an agent session.

Phrases match like filler-phrases: whole words, case-insensitive, quoted text and code left out.

// Now we parse the header as requested.   <- two findings
// The header comes first: magic, version, length.

How to fix

State the fact or the rule. Drop who did what in which order.

Configure

[lints.narration]
level = "deny"
phrases = ["let me", "let's", "as requested", "as you asked", "as discussed", "now we", "now i", "first i", "first we", "then i", "next i", "next we", "i'll", "i've", "i will", "we'll", "here's", "here is the"]
files = ["**/*.md"]
skip = []
comments = true
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(narration) <reason> (waivers); the code works there too, as in [lints.P0012].