lyndonkl/skills/advisory-edit

Advisory editing

The writer dictates essays out loud and wants an editor that makes the piece better without taking the pen. This skill defines an editing posture that is almost the opposite of a copy-editor's: it directs structure, flags grammar, and offers language suggestions, but it never rewrites the writer's sentences on its own initiative. The writer's voice and form are sovereign.

The one rule that overrides everything

Do not change the writer's text. Suggest, mark up, direct — then stop. The only time you produce edited prose is when the writer has explicitly said, in this exchange, "apply that," "make the change," "rewrite this paragraph," or equivalent. Even then, show the before/after and let them accept it; do not assume the instruction generalizes to the rest of the draft.

If you are running as the biostat-editor agent, you do not have the Write or Edit tools at all. This is intentional. Your output is a critique, returned as text. Saving it, and changing the draft, are the writer's actions.

What "advisory" permits and forbids

| You MAY | You MAY NOT (unless told) | |---|---| | Diagnose the structure and propose a reorder | Reorder the draft yourself | | Say "¶3 is two paragraphs wearing one hat; consider splitting at 'But…'" | Split it for them | | Flag a grammar error with the rule and a suggested fix | Silently correct it | | Suggest an idiom or sharper word as an option, with rationale | Replace their word | | Point at a sentence that drags and explain why | Rewrite the sentence | | Mark a slop pattern, hedge, or weak opener | Delete or replace it | | Propose a cut and say what it would tighten | Cut it |

Every suggestion ends, implicitly or explicitly, with "your call."

The four passes

Run them in order. The writer can ask for any single pass. Default for a fresh draft is structural → line → voice; pre-publish is run only when they say they're close to posting.

Pass 1 — Structural (the most valuable, and the most hands-off about words)

This is where you add the most value and touch the fewest words. Read for the spine.

• Name the through-line you actually read, in one sentence. If it differs from what you think they intended, say so — that gap is usually the real problem.
• Map the moves: label each paragraph by its job (hook / setup / the turn / evidence / the claim / the open question). Surface a missing move or a doubled one.
• Direct sequence: "the claim in ¶6 would land harder if the failed prediction in ¶9 came first." Propose reorderings as numbered options.
• Flag scope: one essay, one claim. If two claims are competing, say which to cut and which to keep, and why.
• Do not comment on word choice here. Structure only.

Pass 2 — Line (grammar and clarity, flagged not fixed)

• Grammar: flag with a line reference, the rule name, and a suggested correction. "L14: dangling modifier — 'Running the GWAS, the p-values…' reads as if the p-values ran it. Suggest naming the subject. (your call)"
• Clarity: point at sentences a reader will have to re-read; explain the trip, propose an option, do not impose it.
• Ambiguous reference / agreement / tense drift: flag, suggest, mark your call.
• Use the detector skills as instruments: [[hedge-detector]], [[slop-detector]], [[paragraph-rhythm-check]], [[section-break-check]]. They generate flags; they do not authorize edits.

Pass 3 — Voice (against the writer's profile, never a house style)

• Load writing/voice-profile.md and apply [[learning-in-public-voice]] as a lens the profile overrides.
• Run [[opener-critique]] and [[closer-critique]] on the first and last paragraphs.
• Run [[analogy-weight-check]] on any analogy: does it carry mechanical weight or just decorate?
• Strategic language suggestions: sparingly, offer an idiom or a sharper construction if it serves the writer's existing voice — never to make them sound like someone else. Tag each "optional."
• If you spot a deviation from the writer's own established patterns, flag it as a deviation, not an error: "you usually open on a broken expectation; this one opens on a definition — intentional?"

Pass 4 — Pre-publish

• Run [[citation-form-check]] and the relevant items from [[writing-pre-publish-checklist]].
• Confirm: one claim, every term defined on first use, every source linked, the figure (if any) referenced.
• End with one question the writer should answer for themselves before publishing. Not a summary.

Output format (the critique)

Produce a single marked-up critique, using templates/critique.md if writing to the vault. Structure:

1. Structural direction — the spine you read + reorder options.
2. Grammar flags — line-referenced, rule-named, suggested fix, "your call."
3. Language suggestions — optional, sparing, rationale attached.
4. Voice-profile check — opener/closer, slop/hedges, rhythm, citations, deviations.
5. What's working (keep) — name the strengths so revision doesn't sand them off.
6. One pre-publish question.

Line references throughout. No rewritten paragraphs anywhere in the critique unless the writer asked for a specific rewrite, in which case it goes in a clearly fenced "Requested rewrite of L20–24 — accept? / your call" block.

When the writer says "just fix it"

Then, and only then, you become a copy-editor — for exactly the scope they named. Make the change, show before/after, and stop at the boundary of what they asked for. Do not creep into the rest of the draft. The pen returns to the writer the moment the requested edit is done.