review-project-pr

name

review-project-pr

description

This skill should be used when the user asks to review a Brainhack School pull request by number (e.g., "/review-project-pr 437" or "review PR 437"). It checks that the PR builds with Hugo, that images are not too heavy, that no stray files (notebooks, data) were added, that the frontmatter date is credible, that links work, and that the content has no typos or leftover garbage. It produces a review report in chat plus a local hugo serve link to inspect the rendered project page. Local-only — it never posts to GitHub.

Review a Brainhack School project PR

Review a student-project PR against the site's conventions and produce a report the user can copy into PR feedback. Everything stays local: never comment on the PR, never push, never modify the main working tree.

Environment facts

• Main repo: /home/pbellec/git/school-brainhack.github.io (remote origin = the upstream school-brainhack repo).
• Use the pinned Hugo at ~/git/brainhack-pr-review/bin/hugo (extended 0.128.0, same version as CI; run_checks.sh auto-downloads it). Do NOT use /usr/bin/hugo (0.92, too old) or /snap/bin/hugo (0.164, rejects a duplicate YAML key in config.yaml that CI tolerates).
• Worktrees do not contain the theme submodule; always pass --themesDir /home/pbellec/git/school-brainhack.github.io/themes to hugo.

Workflow

1. Fetch the PR into an isolated worktree

bash .claude/skills/review-project-pr/scripts/setup_pr_worktree.sh <PR#>

This creates ~/git/brainhack-pr-review/pr-<n> and prints the files changed vs origin/main. Also grab metadata:

gh pr view <PR#> --json title,author,createdAt,body,url

2. Run the mechanical checks

bash .claude/skills/review-project-pr/scripts/run_checks.sh ~/git/brainhack-pr-review/pr-<n>

This prints [BUILD], [IMAGES], [STRAY], and [LINKS] sections with PASS/WARN/FAIL lines. Interpret them; downgrade link FAILs to WARN when the site is known to block bots.

3. Qualitative review

Read references/checklist.md for the full rubric, then read the PR's index.md in the worktree and check:

• Date credibility: frontmatter date: vs the PR's createdAt and the current school edition.
• Frontmatter conventions: type: "project", lowercase tags, ~75-word summary, image: file exists, hyphenated slug.
• Internal links/images: relative references in index.md resolve, and the built page under <worktree>/public/project/<slug>/ contains them.
• Typos: genuine misspellings/grammar errors with locations — not style nits.
• Garbage: leftover template text, duplicated blocks, broken shortcodes, merge-conflict markers, secrets, unrelated content.

4. Serve the preview

Kill any previous preview, then start hugo serve in the background on port 1414 (1313 is left free for the user's own serve):

pkill -f "hugo serve.*1414" 2>/dev/null
cd ~/git/brainhack-pr-review/pr-<n> && ~/git/brainhack-pr-review/bin/hugo serve --port 1414 --bind 127.0.0.1 \
  --themesDir /home/pbellec/git/school-brainhack.github.io/themes

Run it with run_in_background: true. Determine the slug's rendered URL path (Hugo lowercases it) and include http://localhost:1414/project/<slug>/ in the report.

5. Report

Use the report template at the end of references/checklist.md: lead with an overall verdict (✅ / ⚠️ / ❌), then a summary table, then findings written so they can be copy-pasted as PR feedback, then the preview link.

Cleanup

Reviewing the same PR again refreshes the same worktree automatically. To clean up manually: git worktree remove --force ~/git/brainhack-pr-review/pr-<n> from the main repo.