47 lines
2.2 KiB
Markdown
47 lines
2.2 KiB
Markdown
# 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
|