review-comments

name	review-comments
description	Audit comments across the C# and Python codebase against the comment policy in AGENTS.md, then remove or rewrite the ones that don't earn their place. Use when the user wants to clean up comments, reassess comment value, prune redundant comments, or enforce the comment policy. Optional arg scopes the review — a path (e.g. RaceDataDownloader/), "changed" (git-modified files), or "staged".

Audit existing comments in the codebase and remove the ones that don't match the project's comment policy. Bias toward keeping anything whose value is uncertain — wrongly deleting a genuine why comment costs more than leaving one borderline comment.

1. Load the policy (source of truth)

Read the "### Comments" section of AGENTS.md and treat it as the rubric. Do not rely on a copy of the rules here — they may have changed. Every keep/delete decision must trace back to a line in that policy.

2. Scope

• No arg → whole codebase: *.cs (excluding bin/, obj/, *.g.cs, *.Designer.cs, anything <auto-generated>) and *.py (the race_analytics/ package, tests/, and *.py scripts — not gitignored nbconvert output under notebooks/ or Data/).
• A path → restrict to files under it.
• changed → only files modified vs. the base branch (git diff --name-only main... plus working-tree changes); staged → only staged files.

A whole-repo audit is large. For broad scope, fan out with Explore/general-purpose subagents — one per top-level area (RaceDataDownloader/, RacePredictor.Core/, the test projects, race_analytics/) — each returning a structured list of comment findings, then review and apply centrally. Read files to judge comments in context; never decide from a grep line alone.

3. NEVER remove these (not policy-eligible comments)

These start with comment syntax but are functional, directive, or API surface. Leaving one of these in place is correct; deleting one is a bug.

Python

• Tooling pragmas: # type: ignore, # pyright: ignore[...], # noqa/# noqa: <code>, # ruff: noqa, # pragma: no cover, # fmt: off/# fmt: on, # isort: skip
• Shebangs (#!...) and encoding cookies (# -*- coding: ... -*-)
• # that appears inside a string literal, f-string, or regex — not a comment
• Docstrings ("""...""") — out of scope; don't touch them

C#

• Preprocessor directives — #region/#endregion, #pragma, #nullable, #if/#endif, #define (these aren't comments)
• // <auto-generated> markers and license/header blocks
• // appearing inside a string (URLs like https://, paths) — not a comment
• XML doc comments (/// <summary>) on public API surface — the policy reserves these. (On private methods / test helpers they ARE candidates per the policy.)

Skip non-code files entirely — notably Verify snapshots (*.verified.txt).

4. Classify each remaining comment

For every policy-eligible comment, assign one verdict:

• DELETE — restates the code (the what), narrates a step (# load the data, // build options), paraphrases the line below, is an ephemeral reference (PRD/ticket/phase number, "legacy X"), or is a /// block on a private/test member.
• REWRITE / RENAME — the comment exists only because a name is unclear, or it buries a real why in noise. Prefer renaming the symbol (propose the rename) over keeping the comment; trim a genuine why to 1–2 lines.
• KEEP — carries non-obvious intent the code can't: external-system quirks (racingpost.com markup, CsvHelper), timing/ordering constraints, invariants (idempotency), or a leakage/ML caveat.

Separately flag commented-out code as DELETE (dead code), but list it under its own heading so the user sees it's a distinct category.

5. Propose, then apply

1. Present findings as a concise list grouped by file: path:line → the comment text → verdict → one-line reason. Batch by directory if large.
2. Wait for approval before editing. This mirrors the other skills in this repo — never auto-apply a sweep of deletions.
3. On approval, apply with Edit (remove only the comment lines / trailing comments; never alter surrounding logic). Approved renames are separate edits.

6. Verify (mandatory)

Comment removal must not change behaviour — run the gates from AGENTS.md over the touched languages to confirm nothing structural was broken (e.g. a line that wasn't actually a comment):

# if C# files were touched
dotnet build && dotnet test
# if Python files were touched
pre-commit run --all-files
python -m pytest tests/

Then report: count removed/rewritten/kept per file, and surface anything you deliberately left because its value was genuinely ambiguous. Commit only if the user asks.