# 07. Comments hygiene check (first end-to-end check)

meta:
  id: pygienium-07
  feature: pygienium
  priority: P1
  depends_on: [pygienium-06]
  tags: [check, e2e-reference]

objective:

- Implement the comments hygiene check as the first full end-to-end check, serving as the reference pattern for the remaining checks: remove low-value comments, tighten verbose ones, keep "why" comments.

deliverables:

- `src/checks/comments.ts`: a `CheckDefinition` with `buildScanTask` and `buildFixTask`
- `agents/comments-scanner.md` and `agents/comments-fixer.md` (or reuse generic scanner/fixer with a check-specific rubric embedded in the task text)
- Rubric encoded in task text: comments that restate code = remove; verbose narration = tighten; `why` comments = keep; self-explanatory code = no comment needed; short + high value
- `/pygienium-comments` runs E2E: recon → agent scans for comment smells → (on `--fix`) agent edits → report of changes

steps:

- Author the check definition: name `comments`, phaseId `C1`, allowedTools for analysis = read/bash/grep; for fix = read/edit/write/bash
- Build scan task text instructing the agent to read candidates from recon, identify comment smells, write findings to `pygienium/checks/comments/findings.md` with per-file line refs
- Build fix task text: apply safe removals/tightenings, leave `why` comments, write `changes.md` summarizing edits and anything needing human review
- Register the check in index.ts via `registerCheck`
- Implement `gate(cwd)`: findings.md exists

tests:

- Integration: create a temp file with restating comments + a `why` comment; run `/pygienium-comments --fix`; assert restating comments removed, why comment kept, changes.md present

acceptance_criteria:

- `/pygienium-comments` produces findings.md without `--fix`
- With `--fix`, low-value comments are removed and `why` comments survive
- run-state marks the check complete and artifacts are recorded

validation:

- Inspect `pygienium/checks/comments/{findings.md,changes.md}` after a run

notes:

- This task proves the whole framework works; prioritize getting it green before 08-11
- The rubric is the user's spec: short + high value; what-comments bad, why-comments good