203 lines
5.2 KiB
Markdown
203 lines
5.2 KiB
Markdown
---
|
|
name: pr-report
|
|
description: >
|
|
Review a pull request or contribution deeply, explain it tutorial-style for a
|
|
maintainer, and produce a polished report artifact such as HTML or Markdown.
|
|
Use when asked to analyze a PR, explain a contributor's design decisions,
|
|
compare it with similar systems, or prepare a merge recommendation.
|
|
---
|
|
|
|
# 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:
|
|
|
|
1. Executive summary
|
|
2. What the PR actually adds
|
|
3. Tutorial: how the system works
|
|
4. Strengths
|
|
5. Main findings
|
|
6. Comparisons
|
|
7. 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.
|