| name | code-review |
| description | Use when retrieving, triaging, or resolving GitHub PR review comments in the website repo via make pr-comments (PR=<num>, FORMAT=text|json|markdown) — categorize each finding (committable suggestion, bug, architecture, complexity, test gap, question), route it to the right specialist skill, then re-validate with make format, focused Jest/Playwright suites, and make lint. |
Code Review Workflow (PR Comments)
Pull unresolved PR review comments, triage each one, fix it at the right level, and
re-validate with the project gates. The command surface is the website Makefile;
make pr-comments wraps scripts/get-pr-comments.sh.
Quick Start
make pr-comments
make pr-comments PR=304
make pr-comments FORMAT=json
make pr-comments PR=304 FORMAT=markdown
FORMAT is text (default, human-readable), json, or markdown.- With no
PR, the script auto-detects the PR for the checked-out branch.
- Needs an authenticated
gh (gh auth status) and jq on PATH.
Resolve comments in priority order — reproduce bugs first, then committable
suggestions, then architecture, complexity, and test gaps — and finish with the
verification gate below.
Categorize And Route
Read every comment before changing code. Classify each finding, then route it to the
companion skill that owns that concern instead of patching in place.
| Finding category | How to resolve |
|---|
| Committable suggestion | Apply only if correct for the nearby code, then re-verify |
| Bug or regression | Reproduce with a failing test, fix, keep the test |
| Architecture concern | Use the code-organization skill; re-check make lint-deps |
| Complexity concern | Use the complexity-management skill; watch qlty smells |
| Test gap | Add coverage per agents.md at the smallest useful layer |
| Question | Answer in the thread or make the code self-explanatory |
Architecture comments (cross-feature imports, deep paths past a feature barrel,
shared-layer-into-feature edges) map to the real .dependency-cruiser.js rules
surfaced by make lint-deps. Complexity comments map to the qlty [smells] analyzer
configured in .qlty/qlty.toml, which posts as PR bot comments — reduce the function,
do not silence the bot.
Verification
Run make format (Prettier) before make lint so formatting churn never trips the
lint gate. Then run the focused suites the comments actually touched.
make format
make lint
Add the layer that exercises the change. Prefix unit suites with CI=1 to run them
locally without Docker.
CI=1 make test-unit-client
CI=1 make test-unit-server
make test-e2e
make test-visual
For a deliberate, reviewed UI change that left its baselines stale, regenerate with
make test-visual-update and inspect the diff before committing — never blanket-update
snapshots to clear a red check.
Rules
- Do not apply a suggestion blindly; read the surrounding feature first.
- Do not weaken a gate to win silence: no lowering of
eslint.config.mjs,
tsconfig.json, .dependency-cruiser.js, .markdownlint.yaml, or the
.qlty/qlty.toml smell thresholds.
- Do not add
eslint-disable, @ts-ignore, @ts-nocheck, @ts-expect-error,
prettier-ignore, or markdownlint-disable; fix the underlying code or type instead.
- Assert user-facing behavior (
getByRole, getByLabelText, getByText, localized
t() strings), not implementation details — see agents.md.
- Re-run
make pr-comments before declaring the review resolved.
Related Guides
Confirm the active task against ../AI-AGENT-GUIDE.md and
../SKILL-DECISION-GUIDE.md so every relevant companion
skill is consulted before you finish.
Line Length Disclosure
Before presenting changes, scan the changed text files for lines longer than 100
characters (the Prettier printWidth). If any exist, report each path:line with its
measured length. Treat this as disclosure, not failure, unless an actual gate fails.
Supporting Files
