Editorial sweep — progress tracker

Converting the whole paper corpus to the EDITORIAL.md rules, above all rule 3: no first person in scored reports (Kin, 2026-08-03). Fundamentals ($25) are exempt — that voice is the product.

Per paper the loop is:

cd /Users/kinlane/GitHub/api-evangelist/papers

# 1. see what is left in one paper (checks the body AND its _papers/ teaser)
python3 bin/lint-editorial.py --paper <slug>

# 2. rewrite by hand — recast the sentence, never regex the pronoun away
# 3. confirm clean
python3 bin/lint-editorial.py --paper <slug>

# 4. rebuild the sellable artifacts from the rewritten README
python3 scripts/build_artifacts.py <slug>

Both files must be done. <slug>/README.md is what the PDF/DOCX are built from; _papers/<slug>.md is the storefront teaser, and its summary: and outline: fields carry first person too. Fixing only the body leaves “I” on the public product page.

Artifacts are NOT published by this loop. build_artifacts.py writes to gitignored dist/. Uploading to private S3 is a separate, outward-facing step — see the sector-report skill, Step 7. Until that runs, buyers still download the pre-sweep PDF.

Done — 96 of 98 report bodies at zero

The whole corpus is converted except the two Personalized Checklists (checklist-telstra, checklist-cisco), which are exempt by decision — first person is load-bearing in a document addressed to one named company, and Kin confirmed they are not a concern.

Every converted report has had its PDF/DOCX rebuilt from the rewritten README.

Corpus: 1,983 errors → 39, all of them in the two exempt checklists.

⚠️ Batch passes MUST go through bin/sweep-replace.py

Early batch passes were ad-hoc for f in glob("*/README.md") loops, which silently rewrote the exempt paper types too. Fundamentals and Personalized Checklists are first-person BY DESIGN, so those edits were wrong — one produced a broken sentence (“…and This paper opens by admitting I have not”), another mixed voice (“API Evangelist wrote policies for how we used SwaggerHub”). All 14 affected files were reverted with git checkout and re-verified at 0 errors.

bin/sweep-replace.py now enforces the exemption in one place and reports every exempt file a pass would have hit, so a skip is never silent:

import sys; sys.path.insert(0, "bin")
from sweep_replace import batch
batch([(r"\bI have measured\b", "measured in this series")])

python3 bin/sweep-replace.py --check lists the 21 exempt files (19 Fundamentals + 2 checklists). Checklists are matched by slug prefix because they are off-storefront and have no _papers/ teaser for the type lookup to read.

Corpus-wide passes already applied

These were identical text repeated across many papers, so they were fixed once and applied everywhere rather than per paper:

• Shared author bio — “I am Kin Lane, the API Evangelist. For sixteen years I have studied…” → “Kin Lane is the API Evangelist. Since 2010 the practice has studied…” (27 files)
• Instrument ownership — “the same rubric I apply to Stripe” → “the same rubric applied to Stripe”; “my rubric” → “the rubric” (63 files)
• Repeated sentences — the closing “I’d welcome the conversation” CTA (35), “I do not score funds on returns” (22), “I score what the portfolio ships” (24), “my catalog” → “the catalog” (66), the peer-benchmark methodology line (19), and others (250 replacements total)
• Killed phrase — “trying to tell a real platform from a compliance filing” → “trying to see which programs went beyond the mandate and which stopped at it” (the banking quartet, 8 files)

• Portfolio-report stock phrases — “an artifact of who I have catalogued”, “A caveat I will not bury”, “A note for the skeptics, and I am one”, “This report is a living document: I re-pull and re-score…”, the “contract nobody checks” argument, and ~20 more (128 file-touches)

• Second stock-phrase pass — “Anti-patterns I’ll be watching for” (24 across headings and outlines), “the checklist I bring to conversations”, “Where I’ll keep this current”, and the decade-skeptical-of-governments opener (50 touches)

• Banking quartet shared narrative — the “I changed my mind in public” reversal, the malicious-compliance line, and the sector-mapping opener, shared across all four country cuts (30 touches)

• Regex templates with variable slots — the portfolio opener I read <Fund>'s portfolio the way a machine reads it, I could pull, parse, and score, of any fund I have measured/scored, I will be careful and show my work, my pipeline, my harvest, and ~50 more patterns (~310 replacements). Once literal phrases run dry, switch to regex with capture groups — the portfolio and market reports are template-generated, so the variable slot is usually just a fund or sector name.

Batching these first is what makes the per-paper work tractable — it is the same edit repeated, not a judgment call. Re-check for new stock phrases every so often as the tail shortens.

Remaining

Nothing on rule 3. What is left is rule 4 (density), untouched by this sweep:

• 244 sentences over 60 words
• 59 sentences with 3+ em-dash clauses

That is the “AI-slop” tell Claire named, and it wants its own pass — it is a rewriting job, not a substitution job. The single biggest cluster is the summary: field in every _papers/*.md teaser, which is one enormous sentence by house convention (up to 175 words).

Open decisions

1. Personalized Checklists (checklist-*) — exempt or not? SKIPPED in the sweep pending a decision. These are addressed directly to one provider (“your gaps”, “I checked all five file trees”, “two of these are my defects, not yours”). The first person is doing real work there: it says a human actually looked, and it owns API Evangelist’s own bugs to the company’s face. Converting “two of these are my defects” to third person reads as distancing at exactly the moment the document is taking responsibility. Same family of exception as Fundamentals — but it is a $1,500 sold product, so it is Kin’s call, not an assumption to make.
2. Fundamentals ($25) — exempt or not? Currently exempt at the document level, on the basis that sixteen years of first-person experience is that product. 18 of them use “I”. One line in the linter flips it. NOTE: the exemption had two bugs, both now fixed — the possessive rule’s label used a hyphen so it slipped the check, and “when I score API estates” (Kin describing his own practice, not claiming the instrument) was being flagged. Fundamentals now lint at 0 errors, so the corpus number no longer hides them.
3. The teaser summary: field is one enormous sentence — up to 175 words — across all 95 papers. It trips R4 every time. That is a house pattern, so it should be decided once for the whole corpus rather than paper by paper.
4. 250 long sentences and 59 em-dash pile-ups corpus-wide (rule 4, the “AI-slop” tell). Not addressed by this sweep; worth its own pass.