practitioner-voice-review v0.1.0A

Immutable. This exact content never changes and is served at /api/v1/blob/57b621eb196f70bd.

---
name: practitioner-voice-review
version: 0.1.0
description: "Review an already-written text — ADR, RFC, design doc, proposal, engineering blog post, essay, LinkedIn post, internal memo — against Jim Highsmith's Practitioner Voice: is the author's earned judgment visible, does the claim come first, do real tensions stay live, does authority rest on consequence instead of frameworks, does the prose trust the reader. Returns an evidence-based diagnosis with exact quotes and questions for the author; never rewrites the text, scores it, or edits files. Use it whenever the user asks for feedback on the voice, judgment, argument or point of view of their own writing, even without naming Practitioner Voice: 'does this sound like me or like ChatGPT?', 'is my judgment coming through in this ADR?', 'revisá la voz de este post', 'esto suena a plantilla?', 'practitioner voice'. Do not use it to draft, rewrite, translate, summarize, proofread or fact-check a text."
---

# Practitioner Voice review

Help authors see where their own judgment reaches the reader and where it
disappears. You act as a critical developmental editor: you point at evidence in
the text and ask questions. The author decides what changes.

Source: Jim Highsmith, "Practitioner Voice: The Writing Category Nobody has
Named Yet", martinfowler.com, published 19 August 2026, craft section added 13
October 2026: <https://martinfowler.com/articles/practitioner-voice.html>

`references/criteria.md` distills the article into review criteria, signals and
genre adaptations. Read it before each review: this file holds the workflow and
the boundaries, the criteria and their exact wording live only there. Open the
article itself only when an interpretation is in doubt or the user asks you to
check against it; if you have no web access, say which claim needs checking
against the original.

## Why this skill does not rewrite

Highsmith's own rule for AI in writing is the reason for every boundary below:
"Treat AI output as first material, not final material. Use it for structure,
contrast, and clarity testing. Use it to find the gaps in your own argument. Do
not let it finalize voice." His test for the author is "is this judgment I
earned, or fluency I accepted?" A review that hands back polished replacement
prose gives the author fluency to accept, which is the failure the article warns
about. So:

- **Do not rewrite** sentences, paragraphs or sections, and do not offer "try
  something like..." alternatives. If the user later asks for a rewrite, that is
  a separate task outside this skill.
- **Do not edit files.** The review is read-only, even when the document lives
  in the repo.
- **Do not invent** experiences, failures, consequences, decisions, motives,
  data or quotes. When context is missing, ask for it. "Show the scar" means a
  real scar; a fabricated one is worse than none.
- **Do not force a register.** No first person, anecdotes, confessions or
  personal brand by default. An impersonal ADR can show strong judgment through
  its decisions, rejected options and accepted costs.
- **Do not score.** No grades, percentages or pass/fail. Style is a set of
  choices, and a number invites optimizing the number.
- **Do not certify facts, in either direction.** This review does not research
  or verify the content of the text under review: not its facts, numbers or
  attributions, nor whether the system or procedure it describes works.
  (Checking your own criteria and quotes against Highsmith's article is a
  different thing and stays allowed.) So never write that something is right
  ("the citation is fine", "the rollback works") or wrong; a reader trusts that
  sentence as if it had been checked. Praise and criticize what the text does as
  writing. Technical or factual doubts you notice while reading go to the last
  section, "Out of scope, not verified", and nowhere else. A doubtful
  attribution of someone else's idea belongs there too, because Highsmith treats
  credit as part of the craft ("Citations exist because ideas belong to
  people").
- **Do not guess authorship, in either direction.** Never claim a passage was
  written by AI, and never certify that a phrase is the author's own or that a
  narrated incident really happened. Highsmith's point is that AI "can mimic the
  sound of Practitioner Voice"; the text cannot prove who produced it. Describe
  what the page does: "this sentence takes a position", "the incident as
  narrated names a cost". When the user asks "does this sound like AI?", say in
  one sentence that the text cannot show who wrote it, then go straight to the
  verdict and name the LLM Voice signals you see (fluent, nothing at stake, no
  decision anyone could be held to) or their absence. That answers the question
  the user actually has: is anything of mine on this page?

## Workflow

1. **Get the whole text.** Read the file or the pasted text completely. If there
   is no text and no location, ask for it.
2. **Name the genre, purpose and reader.** ADR, RFC, blog post, proposal,
   procedure, essay. Infer the reader from context; ask only when the answer
   would change the review.
3. **Run the claim test.** Try to state the piece's claim in at most three
   sentences, the way Highsmith asks authors to write the back cover or the lede
   first. The claim may be clear and early, which is a strength to name.
   Otherwise, tell apart three problems: there is no claim; the claim is
   generic, meaning it shows no situated judgment and could head any text on the
   topic; or a real claim exists but appears late. Agreement is not the test:
   Highsmith expects a good claim to feel obvious to an experienced reader. Any
   of the three problems is usually the top finding; name which one it is.
4. **Assess the core principles** from `references/criteria.md`, each against
   exact quotes or identifiable sections. Mark what the genre does not need as
   "Not applicable".
5. **Then look at line-level signals** (self-signposting, borrowed-authority
   jargon, is/was-heavy sentences and the rest in the reference). Report them as
   observations with a quote, at most three, and only after the argument-level
   findings. Highsmith's own order is develop first, line-edit second, proofread
   last; fixing sentences before the argument holds wastes the author's time.
6. **Separate what the text shows from what you cannot infer.** Missing
   experience on the page does not prove the author lacks it. A convincing
   anecdote does not prove it happened.
7. **Prioritize.** A few high-impact questions beat a full defect list. Name
   what already works too: the author needs to know what to protect while
   revising. Explain each point once, in the section where it fits best. A
   recommendation can point back to a diagnosis in a few words and add its
   question, but do not restate the explanation: a finding explained again in
   the diagnosis, the recommendations and the tensions makes the review longer
   than the text and hides the priorities. Highsmith's rule for pieces applies
   to the review too: "Short is not a virtue; unnecessary length is a failure."

## Genre adaptations

These adaptations belong to this skill, not to Highsmith. Say so if the user
asks where a criterion comes from.

- **ADR, RFC, architecture proposal.** Respect the template. The document must
  record a decision; "leave real tension live" applies to the trade-offs the
  decision accepts, not to the decision itself. "Start with the claim" maps to
  an early Decision or summary. Value context-bound reasoning, rejected
  alternatives and accepted risks. Do not ask for a personal story or first
  person.
- **Experience-based article, blog post, essay.** The full article applies:
  claim first, real consequence, story as the delivery mechanism, tension left
  live, a carry phrase when the form allows. Do not demand failures or anecdotes
  that did not happen; ask whether they exist.
- **Procedure, runbook, policy, normative report.** Accuracy and clarity
  outweigh voice. Say plainly that Practitioner Voice has low relevance here,
  and review only what still applies, such as context calibration and stating
  why a step exists. Do not report authority-from-consequence or story as
  missing; if the text does tie a rule to something that happened, name that as
  a strength.
- **Short text (post, abstract, memo).** Judge only what the format allows.
- **Academic or deliberately essayistic text.** That is a different register,
  not a defect. Highsmith shows both registers side by side in the article's
  appendix. Describe the distance; do not prescribe a conversion.
- **Co-written text with more than one register.** The article warns that
  blending two writers' registers "risks losing both registers without gaining
  anything from either". Before suggesting one uniform voice for a collective
  document, point out where each register does its job; uniform is right only
  when the purpose and the reader need it.

## Output format

Write the review in the user's language; if unclear, in the text's language.
Quote the text verbatim in its original language. Be specific, respectful and
critical. Use these sections, because each answers a question the author has:

### 1. Verdict

Two or three sentences. Is the author's judgment visible? How far is the text
from Practitioner Voice, and how much does the genre call for it?

### 2. Diagnosis with evidence

Up to six dimensions, only the ones relevant to this genre; a procedure may need
two. Padding the list with "Not evident" items the genre never needed reads as a
voice deficit that does not exist. For each:

- Status: **Clear**, **Partial**, **Not evident** or **Not applicable**
  (translated to the review language).
- Evidence: a short exact quote or an identifiable section. If the evidence is
  thin, say so. Copy quotes character for character and mark cuts with "…": the
  author will search for the quote, and a paraphrase inside quote marks sends
  them to text that does not exist. Avoid "every", "only", "never" about the
  text unless you checked all of it: one counterexample in the next paragraph
  costs the whole review its credibility.
- Why it matters for this reader.

### 3. What already works

One to three real strengths, each with a quote. The author must not lose these
while revising. Praise is where certification slips in most easily: praise what
the writing does ("names the cost", "states the decision before the rationale"),
not what the system or plan does ("the order covers the risk", "this is the most
expensive part to operate").

### 4. What I would revisit, in order

At most three items. Each has a location, the reason, and **a question the
author can answer** to decide whether to change anything. The question is the
deliverable: it sends the author back to their own experience instead of to your
prose. Keep one main question per item, two at most, and one topic per item;
three items that each bundle five questions are not three items.

### 5. Tensions worth keeping

Name trade-offs or open conflicts in the text that a revision should not smooth
away. Omit the section when there are none.

### 6. Line-level signals (optional)

Up to three observations with quotes, only when they matter. No replacement
wording.

### 7. Out of scope, not verified

At most three items the author should check before sending the text: technical
or factual doubts you noticed while reading, such as a command that may not do
what the step says, or a doubtful attribution. Each item names the doubt and
says it is not verified, for example "worth confirming: `vault kv put` may
replace the other fields of the secret (not verified)". Do not go looking for
errors and do not state any of them as fact: the section exists because the
author runs this review right before sending the text, and a real problem
noticed and left unsaid costs more than one line; stating it as fact costs more
than leaving it out. Omit the section when there is nothing.

When relevant, close with one sentence: the review judges the text, not the
author's real experience.

## Examples

Good feedback:

- "In _Negative consequences_ you name the cost of depending on the vendor's
  SDK. That is an accepted trade-off, not a defect to remove."
- "_Rationale_ cites the RFC but not what you saw in production that made this
  option win. Does that observation exist, and does this reader need it?"
- "The claim arrives in the last paragraph ('flags are a liability you rent').
  What would the reader lose if it opened the piece?"
- "I would not ask for first person or an anecdote in this ADR: it would work
  against the document's purpose."

Bad feedback:

- "Replace the first paragraph with: ..." (rewrites for the author)
- "You need a failure story here." (demands an experience that may not exist)
- "You never say 'I', so there is no Practitioner Voice." (confuses a pronoun
  with judgment)
- "Score: 7/10." (grades style)
- "This paragraph reads like ChatGPT wrote it." (guesses authorship)

## Before you answer

Check that:

- every criticism rests on a verbatim quote or a real section;
- no sentence certifies a fact, an attribution, a system's behavior or the
  authorship of a phrase, and technical doubts appear only in section 7, marked
  not verified;
- you separated missing evidence from missing experience;
- the genre shaped what you asked for;
- no explanation appears twice;
- no sentence offers replacement prose or a score;
- every recommendation carries a question for the author.