docs: add PR self-review norms and code flow section

[ian-flores]

Summary

• Creates a new .github/pull_request_template.md with Description, Code Flow, Category of change, and Checklist sections
• Adds a self-review checklist item requiring authors to comment their own diff before opening the PR
• Updates .claude/review-guidelines.md with reviewer responsibilities, code quality fundamentals (encapsulation, DRY, naming, complexity), and the self-review norm

These changes reflect new team norms for balancing PR effort between author and reviewer in an agentic coding workflow.

Test plan

• Verify the PR template renders correctly when opening a new PR
• Verify .claude/review-guidelines.md is accessible to Claude Code sessions

[claude]

Claude finished @ian-flores's task —— View job

---

PR Review: docs: add PR self-review norms and code flow section

Overall this is a solid set of team norms for balancing effort between author and reviewer. Feedback below is mostly about reducing friction and avoiding redundancy with existing conventions.

---

.github/pull_request_template.md

1. # Description heading (line 1)
The # (h1) competes visually with GitHub's own PR title. The other sections use ## — consider ## Description for consistency.

2. ## Issue is inside the HTML comment block (lines 8–11)
Because it's wrapped in ``, the "Issue" heading won't render when the template is used — authors would need to manually uncomment it. If the intent is to prompt linking an issue, move the heading outside the comment:

## Issue

3. Category of change vs. PR title convention (lines 23–30)
The categories overlap with conventional commit types already enforced in the PR title (and mentioned in the template itself). This creates a risk of inconsistency — e.g., an author checks "Bug fix" but titles the PR feat:. Consider either:

• Removing this section and relying on the PR title convention, or
• Adding a note like "This should match your PR title prefix"

4. Checklist completeness (line 33)
just test is good, but CONTRIBUTING.md also lists just format, git diff --exit-code, and just helm-lint as pre-submission steps. Worth considering whether those should appear here too, or if just test alone is sufficient since the others are covered by pre-commit hooks.

---

.claude/review-guidelines.md

5. Code Quality Fundamentals (lines 25–29)
Good placement between Maintainability and Security. The DRY bullet's nuance ("three similar lines can be better than a premature helper") sets the right tone for pragmatic reviews.

6. Self-Review Norm — blanket requirement (line 85)
"If the author hasn't commented their PR, ask them to." could create friction for trivial PRs (typo fixes, version bumps). Consider adding a threshold: "For non-trivial PRs, if the author hasn't commented their diff, ask them to."

---

Note: I was unable to post inline comments via the GitHub review system due to tool permission constraints, so all feedback is consolidated here.

[ian-flores]

Team-operator didn't have a PR template before — this is new. It includes a reminder about the conventional commit format for PR titles since that's enforced by CI and drives semantic versioning.

[ian-flores]

Same self-review checklist item as ptd and ptd-config. Also added just test since that's the standard pre-merge check for this repo.

[ian-flores]

New section. Same reviewer responsibilities framing as the other PTD repos — review the code itself, not just the description.

[ian-flores]

Added code quality fundamentals (encapsulation, DRY, naming, complexity). The existing review-guidelines.md had simplicity and maintainability principles but not these explicit quality checks.