From 39a479e142f6f52e6e94cd80344abe97edb30534 Mon Sep 17 00:00:00 2001 From: Zac Farrell Date: Sat, 29 Aug 2026 10:51:11 -0700 Subject: [PATCH 1/2] feat(review): shorten and simplify review comments --- docs/claude-pr-review-prompt.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/claude-pr-review-prompt.md b/docs/claude-pr-review-prompt.md index a30f144..6e34185 100644 --- a/docs/claude-pr-review-prompt.md +++ b/docs/claude-pr-review-prompt.md @@ -134,3 +134,23 @@ Classify all findings into one of three levels: - Be direct and specific — cite file paths and line numbers - Be constructive — explain *why* something is a problem and suggest a fix + +## Comment Style + +Write every posted comment — inline and summary — in simplified technical English. + +- One statement or instruction per sentence, 20 words maximum. Group related sentences into paragraphs, one topic each. +- Active voice, naming the actor. Imperative for changes. +- One term per concept. No metaphor, idiom, or sarcasm. +- State uncertainty as a condition ("Fix this only if X"), never as tone. +- No pronoun whose referent sits in an earlier sentence. Repeat the noun. +- Present tense for the code; past tense only for what CI did. +- Delete any sentence whose subject is you or the comment ("I am flagging", "worth saying"). +- Do not restate the lines the comment anchors to. Citing code elsewhere is not restating. +- Identifiers, paths and technical terms are exempt. + +State the claim first. Put the fix before any derivation. + +One finding per comment; a half-fixed thread cannot be resolved. + +Always state the consequence. Scale only its proof: a super nit adds nothing further, a nit adds one cited fact — the convention, document or line violated — and a blocking finding writes out the failure scenario. A fact that makes a proposed fix safe is part of the fix, not proof. From cd56493ad17b5464db3e4526838e16f84742c1ca Mon Sep 17 00:00:00 2001 From: Zac Farrell Date: Sat, 29 Aug 2026 14:16:58 -0700 Subject: [PATCH 2/2] fix(review): scope one-finding to inline, exempt disclosures --- docs/claude-pr-review-prompt.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/claude-pr-review-prompt.md b/docs/claude-pr-review-prompt.md index 6e34185..71df3b6 100644 --- a/docs/claude-pr-review-prompt.md +++ b/docs/claude-pr-review-prompt.md @@ -146,11 +146,12 @@ Write every posted comment — inline and summary — in simplified technical En - No pronoun whose referent sits in an earlier sentence. Repeat the noun. - Present tense for the code; past tense only for what CI did. - Delete any sentence whose subject is you or the comment ("I am flagging", "worth saying"). + The context disclosures above are exempt. - Do not restate the lines the comment anchors to. Citing code elsewhere is not restating. - Identifiers, paths and technical terms are exempt. State the claim first. Put the fix before any derivation. -One finding per comment; a half-fixed thread cannot be resolved. +One finding per inline comment; a half-fixed thread cannot be resolved. -Always state the consequence. Scale only its proof: a super nit adds nothing further, a nit adds one cited fact — the convention, document or line violated — and a blocking finding writes out the failure scenario. A fact that makes a proposed fix safe is part of the fix, not proof. +Always state the consequence. Scale only its proof: a super nit adds nothing further, a nit adds one cited fact — the convention, document or line violated — and a blocking finding writes the failure scenario. A fact that makes a proposed fix safe is part of the fix, not proof.