PR Report Skill

Produce a maintainer-grade review of a PR, branch, or large contribution.

Default posture:

• understand the change before judging it

• explain the system as built, not just the diff

• separate architectural problems from product-scope objections

• make a concrete recommendation, not a vague impression

When to Use

Use this skill when the user asks for things like:

• "review this PR deeply"

• "explain this contribution to me"

• "make me a report or webpage for this PR"

• "compare this design to similar systems"

• "should I merge this?"

Outputs

Common outputs:

• standalone HTML report in tmp/reports/...

• Markdown report in report/ or another requested folder

• short maintainer summary in chat

If the user asks for a webpage, build a polished standalone HTML artifact with clear sections and readable visual hierarchy.

Resources bundled with this skill:

• references/style-guide.md for visual direction and report presentation rules

• assets/html-report-starter.html for a reusable standalone HTML/CSS starter

Workflow

1. Acquire and frame the target

Work from local code when possible, not just the GitHub PR page.

Gather:

• target branch or worktree

• diff size and changed subsystems

• relevant repo docs, specs, and invariants

• contributor intent if it is documented in PR text or design docs

Start by answering: what is this change trying to become?

2. Build a mental model of the system

Do not stop at file-by-file notes. Reconstruct the design:

• what new runtime or contract exists

• which layers changed: db, shared types, server, UI, CLI, docs

• lifecycle: install, startup, execution, UI, failure, disablement

• trust boundary: what code runs where, under what authority

For large contributions, include a tutorial-style section that teaches the system from first principles.

3. Review like a maintainer

Findings come first. Order by severity.

Prioritize:

• behavioral regressions

• trust or security gaps

• misleading abstractions

• lifecycle and operational risks

• coupling that will be hard to unwind

• missing tests or unverifiable claims

Always cite concrete file references when possible.

4. Distinguish the objection type

Be explicit about whether a concern is:

• product direction

• architecture

• implementation quality

• rollout strategy

• documentation honesty

Do not hide an architectural objection inside a scope objection.

5. Compare to external precedents when needed

If the contribution introduces a framework or platform concept, compare it to similar open-source systems.

When comparing:

• prefer official docs or source

• focus on extension boundaries, context passing, trust model, and UI ownership

• extract lessons, not just similarities

Good comparison questions:

• Who owns lifecycle?

• Who owns UI composition?

• Is context explicit or ambient?

• Are plugins trusted code or sandboxed code?

• Are extension points named and typed?

6. Make the recommendation actionable

Do not stop at "merge" or "do not merge."

Choose one:

• merge as-is

• merge after specific redesign

• salvage specific pieces

• keep as design research

If rejecting or narrowing, say what should be kept.

Useful recommendation buckets:

• keep the protocol/type model

• redesign the UI boundary

• narrow the initial surface area

• defer third-party execution

• ship a host-owned extension-point model first

7. Build the artifact

Suggested report structure:

• Executive summary

• What the PR actually adds

• Tutorial: how the system works

• Strengths

• Main findings

• Comparisons

• Recommendation

For HTML reports:

• use intentional typography and color

• make navigation easy for long reports

• favor strong section headings and small reference labels

• avoid generic dashboard styling

Before building from scratch, read references/style-guide.md . If a fast polished starter is helpful, begin from assets/html-report-starter.html

and replace the placeholder content with the actual report.

8. Verify before handoff

Check:

• artifact path exists

• findings still match the actual code

• any requested forbidden strings are absent from generated output

• if tests were not run, say so explicitly

Review Heuristics

Plugin and platform work

Watch closely for:

• docs claiming sandboxing while runtime executes trusted host processes

• module-global state used to smuggle React context

• hidden dependence on render order

• plugins reaching into host internals instead of using explicit APIs

• "capabilities" that are really policy labels on top of fully trusted code

Good signs

• typed contracts shared across layers

• explicit extension points

• host-owned lifecycle

• honest trust model

• narrow first rollout with room to grow

Final Response

In chat, summarize:

• where the report is

• your overall call

• the top one or two reasons

• whether verification or tests were skipped

Keep the chat summary shorter than the report itself.