grm/REVIEW_CHECKLIST.md

Review Checklist

This checklist is mandatory for every PR. The automated pr-review CI job checks items marked [auto]. The agent must verify all items marked [manual] before posting an APPROVE review.

The review_pr.py script requires --checklist-confirmed for APPROVE events. This flag attests that every category below has been reviewed.

---

1. Architecture Compliance [auto + manual]

• No business logic in CLI (cli.py): no subprocess, no os.system, no ansible-playbook — delegate to executor.py
• No hardcoded URLs or config values that belong in config.py with env var overrides
• Layer boundaries respected: CLI → runner_manager → executor → subprocess/Ansible. No skipping layers.
• Single Responsibility: each module/function has one reason to change. If a function does two things, split it.
• No circular imports introduced

2. Code Quality and Best Practices [auto + manual]

• No print() in src/ — use click.echo() for user output
• No bare except: — catch specific exceptions
• No broad except Exception: without justification
• No TODO/FIXME/HACK/XXX left in merged code
• No functions > 50 lines (excluding docstrings and decorators)
• No dead code — unused imports, unreachable branches, commented-out code
• No copy-paste duplication — extract shared logic into a helper
• Idiomatic Python — use comprehensions, context managers, dataclasses
• Type hints on all public functions
• No Any type without justification — document why if used
• Error handling complete — all failure paths handled, no silent failures
• Cleanup in error paths — files closed, connections released, temp files removed

3. Security [auto + manual]

• No hardcoded secrets (tokens, passwords, keys in string literals)
• No shell=True in subprocess calls — use argument lists
• No eval() or exec() — use ast.literal_eval if parsing literals
• No secrets in logs or process arguments — pass via env vars or files
• Input validation on all external inputs (CLI args, API responses, file contents)
• No injection vectors — parameterize subprocess args, SQL queries, etc.
• File paths validated — no path traversal (use Path.resolve(), check boundaries)

4. Internationalization (i18n) [auto + manual]

• All user-facing strings wrapped in _() — click.echo(_("...")), error messages, help text, prompts
• No raw English strings in click.echo(), click.ClickException(), or raise messages visible to users
• String interpolation uses named placeholders: _("Hello {name}", name=x) not f"Hello {x}" for translatable strings

5. Testability and Test Coverage [auto + manual]

• Source file changes include corresponding test updates
• 100% coverage maintained (enforced by pytest-cov)
• Tests are fast (< 10 seconds total, enforced by check_test_speed.py)
• Edge cases tested: empty inputs, boundary values, error paths, None/Optional
• No flaky tests — no sleep(), no race conditions, no external dependencies
• Test names describe the scenario: test_<condition>_<expected_result>

6. Performance [manual]

• No unnecessary allocations in hot paths — use generators for large datasets, avoid reading entire files into memory
• Correct data structures — O(1) lookups use set/dict, not list; dict for key-value, set for membership, list for ordered iteration
• No N+1 query patterns in API calls or file I/O — batch operations where possible
• No blocking I/O on hot paths without justification — CLI startup, command execution

7. User Experience [manual]

• Clear error messages — tell the user what went wrong and how to fix it. Example: "Error: Config file not found at /etc/grm.conf. Create it with: grm config init"
• Consistent CLI flag naming — --long-name with --short aliases
• Help text on all commands and options — --help should be useful
• No silent failures — if something fails, the user should know
• Output is actionable — not just "Error" but "Error: X failed because Y. Try Z."

8. Documentation [auto + manual]

• Source changes include doc updates — README, wiki, AGENTS.md as needed
• New functions/classes have docstrings — Google style
• Public API changes documented in CHANGELOG (auto-generated by git-cliff)
• AGENTS.md updated if workflow, conventions, or processes changed
• No stale documentation — if code changed, docs must reflect it

9. Workflow Compliance [manual]

• PR title matches Vikunja task title (GRM-N: <task title>)
• Commit messages follow conventional format (type: description)
• No force-push after review — creates new commits and re-trigger CI
• Branch is up to date with master before merging
• No merge commits in the PR branch — use squash merge via auto-merge

10. Extensibility and Maintainability [manual]

• Open/Closed Principle — code is open for extension, closed for modification. New behavior via new functions/classes, not by modifying existing ones
• No magic numbers — constants are named and documented
• Configuration over hardcoding — use config.py with env var overrides
• Future-proof error handling — don't catch specific error messages that may change
• Dependencies are justified — no new dependency without rationale

11. Resource Management [auto + manual]

• File handles closed — use with statements or explicit close() in finally
• Subprocess resources cleaned up — call .wait() or .communicate()
• Temporary files deleted — use tempfile.TemporaryDirectory() or cleanup in finally
• No resource leaks in error paths — try/finally or context managers for cleanup

12. Backwards Compatibility [manual]

• No breaking changes to public API — or documented as major version bump
• Removed functions deprecated first — with DeprecationWarning and removal timeline
• Default values added instead of new required arguments
• Return types stable — no changes without major version bump
• Behavior changes documented — no silent behavior changes in existing functions

13. Logging and Observability [manual]

• No sensitive data in logs — tokens, passwords, PII excluded
• Sufficient detail for debugging — context, state, values logged at DEBUG level
• Log levels appropriate — DEBUG for internals, INFO for user actions, WARNING for recoverable issues
• No log spam — loops don't log per iteration, use DEBUG for high-frequency events