diff --git a/modes.ts b/modes.ts index 41bb44f..cea0e2f 100644 --- a/modes.ts +++ b/modes.ts @@ -135,17 +135,20 @@ Only when there are nits that for some reason can't be inlined. Filepaths in nit ## Inline comment shape -Inline comments use the same severity framing as body \`### \` sections, scaled down for line-anchored use: +Inline comments are plain, no-frills anchors on the affected line: -- **Lead with a 1-2 sentence problem statement.** The reader is looking at the line in question, so don't restate what the line says — describe what's wrong with it. Optionally prefix the visible line with a severity emoji (🚨 / ⚠ī¸ / ℹī¸) when severity isn't obvious from context. +- **No emojis.** Do not prefix the visible text with 🚨 / ⚠ī¸ / ℹī¸ or any other emoji. The severity is already communicated by the technical-details block. +- **Lead with a 1-2 sentence problem statement.** The reader is looking at the line in question, so don't restate what the line says — describe what's wrong with it. - **Optional \`
Technical details...
\` collapsible** for findings whose technical context (longer file:line references, related-code snippets, suggested approach, regression-risk notes) would overwhelm the human-readable lead-in. Same plain-markdown bold-header shape as the body technical-details block — see *Inline technical details* above. Encouraged whenever the depth helps a downstream fix-agent; don't force one when the inline lead-in already says everything. - **Visible portion ≤ 2-3 sentences.** If you find yourself writing more, that's the cue to split the depth into the \`Technical details\` collapsible. +- **Multi-site findings go inline too.** A finding that spans multiple files or multiple lines is still an inline comment — anchor it to the PRIMARY causal site (the place a developer would fix first), and list the other affected sites in the \`**Affected sites:**\` section of the technical-details block. "Spans multiple files" is NOT a reason to put a finding in the body. +- **Anchor to the exact problem line.** Use the `| newLine |` column to find the specific line where the problematic symbol is **defined or first assigned** — not a nearby related line. If the symbol is `isAnyPending`, anchor to the line that defines `isAnyPending`, not a line that uses a different variable nearby. ## Body-wide rules - **Inline-vs-body discipline (repeated for emphasis):** anything that anchors to a specific line goes inline (with a \`
Technical details
\` block when the implications are broad). The body is for non-anchorable concerns only — absence, sequencing, design decisions, scope questions, architectural risk. - **No \`### Issues found\` heading** above the issue sections — each \`### \` heading IS the issue. -- **Severity emoji on every \`### \` heading** (🚨 / ⚠ī¸ / ℹī¸). No emoji on the preamble lead-in or anywhere else. +- **Severity emoji on every \`### \` heading** (🚨 / ⚠ī¸ / ℹī¸). No emoji on the preamble lead-in or on inline comments — only body \`### \` headings carry emojis. - **GitHub block-level rendering**: GitHub's markdown parser requires a blank line between ALL block-level elements (HTML tags like \`
\`, \`\`, \`
\`, \`\` and markdown syntax like headings, lists, blockquotes, code fences, paragraphs). Without a blank line, GitHub treats following content as a continuation of the HTML block and renders markdown syntax as literal text. ALWAYS separate block-level elements with a blank line. - **Backtick-wrap** every variable, identifier, or file name when you mention one (in either visible or technical-details portions). - **Don't repeat diff content**, don't include raw \`+123 / -45\` stats, don't include a changelog section, don't use horizontal rules (\`---\`).