contributing

name	contributing
description	Audit the doc-comments and prose in a change against CONTRIBUTING.md and fix what violates the rules. Use before committing or opening a PR, or when asked to check changes against CONTRIBUTING.md. Style-only, not a code review.

Contributing check

Audit the comment and JSDoc prose in a change against the repo-root CONTRIBUTING.md style rules, then fix what violates them. Scope is prose inside comments and doc-comments only. This is not a code review. For code quality use /simplify, for correctness use /review-pr.

Phase 0: Gather scope

Read the repo-root CONTRIBUTING.md first. It is the source of truth. The checks below are its current form. If the file has changed, follow the file.

Get the diff under review:

• git diff @{upstream}...HEAD, falling back to git diff main...HEAD or git diff HEAD~1 when there is no upstream.
• If there are uncommitted changes, or the range diff is empty, also run git diff HEAD and include the working tree.
• If a PR number, branch, or path was passed as an argument, review that instead.

Only added lines are in scope, plus any file the change rewrote whole.

Phase 1: Mechanical sweep

Run these over the added lines and the new or rewritten files. Each is an objective violation once you confirm it sits in a comment or doc-comment, not in code or a string literal.

• Em-dash —. Rewrite as two sentences or a comma.
• Unicode arrows → ← ↔. Rewrite the sentence.
• on-chain. Say "network" or drop it.
• Possessive 's: pattern [A-Za-z]'s . MANUAL confirm each hit. it's, that's, here's are contractions and allowed. Only the possessive is a violation. Drop the 's.
• Semicolon in prose: a // or * line where ; joins two clauses. Split into two sentences. Code semicolons and for (;;) do not count.
• Prose-conjunction +: + standing in for "and" or "then" in a sentence.
• Decorative separators: // -----, // =====, and similar dividers.

Illustrative one-pass scan of added comment lines, adjust the range:

git diff HEAD | grep -nE '^\+' | grep -nE '—|→|←|↔|on-chain|[A-Za-z]'"'"'s '
grep -rnE '^\s*(//|\*).*; ' <changed-files>

Phase 2: Judgment pass

Read each changed doc-comment for the rules a grep cannot catch:

• Leads with one sentence stating WHAT, not HOW. Extra context goes after a blank line.
• Does not restate the signature or the code below it.
• No parenthetical asides. Fold the detail into the sentence or cut it. Technical notation like CIDv1(raw, blake2b-256) or getEntries() is not an aside.
• Does not name the variable in its own doc. Describe what the value holds.
• Prefers full words to abbreviations. cid, evm, sdk are allowed.

Phase 3: Fix

Rewrite each real violation in place, preserving meaning. Two short sentences beat one joined by a dash or semicolon. Skip false positives, a contraction, a code semicolon, technical notation, and note each skip rather than arguing with it. Do not touch prose outside the change unless the change rewrote the whole file.

Phase 4: Report and verify

Summarize what was fixed and what was skipped. Then confirm the change still builds: run the project typecheck, lint, and prettier over the touched files. A comment rewrite can still trip prettier line-length, so do not skip it. Never claim a check passed without running it.