pr-report

1---2name: pr-report3description: >4  Produce a maintainer-grade PR or contribution report as HTML or Markdown. Use5  when asked to deeply review a PR, explain a design, compare systems, or prepare6  a merge recommendation.7---8 9# PR Report Skill10 11Produce a maintainer-grade review of a PR, branch, or large contribution.12 13Default posture:14 15- understand the change before judging it16- explain the system as built, not just the diff17- separate architectural problems from product-scope objections18- make a concrete recommendation, not a vague impression19 20## When to Use21 22Use this skill when the user asks for things like:23 24- "review this PR deeply"25- "explain this contribution to me"26- "make me a report or webpage for this PR"27- "compare this design to similar systems"28- "should I merge this?"29 30## Outputs31 32Common outputs:33 34- standalone HTML report in `tmp/reports/...`35- Markdown report in `report/` or another requested folder36- short maintainer summary in chat37 38If the user asks for a webpage, build a polished standalone HTML artifact with39clear sections and readable visual hierarchy.40 41Resources bundled with this skill:42 43- `references/style-guide.md` for visual direction and report presentation rules44- `assets/html-report-starter.html` for a reusable standalone HTML/CSS starter45 46## Workflow47 48### 1. Acquire and frame the target49 50Work from local code when possible, not just the GitHub PR page.51 52Gather:53 54- target branch or worktree55- diff size and changed subsystems56- relevant repo docs, specs, and invariants57- contributor intent if it is documented in PR text or design docs58 59Start by answering: what is this change *trying* to become?60 61### 2. Build a mental model of the system62 63Do not stop at file-by-file notes. Reconstruct the design:64 65- what new runtime or contract exists66- which layers changed: db, shared types, server, UI, CLI, docs67- lifecycle: install, startup, execution, UI, failure, disablement68- trust boundary: what code runs where, under what authority69 70For large contributions, include a tutorial-style section that teaches the71system from first principles.72 73### 3. Review like a maintainer74 75Findings come first. Order by severity.76 77Prioritize:78 79- behavioral regressions80- trust or security gaps81- misleading abstractions82- lifecycle and operational risks83- coupling that will be hard to unwind84- missing tests or unverifiable claims85 86Always cite concrete file references when possible.87 88### 4. Distinguish the objection type89 90Be explicit about whether a concern is:91 92- product direction93- architecture94- implementation quality95- rollout strategy96- documentation honesty97 98Do not hide an architectural objection inside a scope objection.99 100### 5. Compare to external precedents when needed101 102If the contribution introduces a framework or platform concept, compare it to103similar open-source systems.104 105When comparing:106 107- prefer official docs or source108- focus on extension boundaries, context passing, trust model, and UI ownership109- extract lessons, not just similarities110 111Good comparison questions:112 113- Who owns lifecycle?114- Who owns UI composition?115- Is context explicit or ambient?116- Are plugins trusted code or sandboxed code?117- Are extension points named and typed?118 119### 6. Make the recommendation actionable120 121Do not stop at "merge" or "do not merge."122 123Choose one:124 125- merge as-is126- merge after specific redesign127- salvage specific pieces128- keep as design research129 130If rejecting or narrowing, say what should be kept.131 132Useful recommendation buckets:133 134- keep the protocol/type model135- redesign the UI boundary136- narrow the initial surface area137- defer third-party execution138- ship a host-owned extension-point model first139 140### 7. Build the artifact141 142Suggested report structure:143 1441. Executive summary1452. What the PR actually adds1463. Tutorial: how the system works1474. Strengths1485. Main findings1496. Comparisons1507. Recommendation151 152For HTML reports:153 154- use intentional typography and color155- make navigation easy for long reports156- favor strong section headings and small reference labels157- avoid generic dashboard styling158 159Before building from scratch, read `references/style-guide.md`.160If a fast polished starter is helpful, begin from `assets/html-report-starter.html`161and replace the placeholder content with the actual report.162 163### 8. Verify before handoff164 165Check:166 167- artifact path exists168- findings still match the actual code169- any requested forbidden strings are absent from generated output170- if tests were not run, say so explicitly171 172## Review Heuristics173 174### Plugin and platform work175 176Watch closely for:177 178- docs claiming sandboxing while runtime executes trusted host processes179- module-global state used to smuggle React context180- hidden dependence on render order181- plugins reaching into host internals instead of using explicit APIs182- "capabilities" that are really policy labels on top of fully trusted code183 184### Good signs185 186- typed contracts shared across layers187- explicit extension points188- host-owned lifecycle189- honest trust model190- narrow first rollout with room to grow191 192## Final Response193 194In chat, summarize:195 196- where the report is197- your overall call198- the top one or two reasons199- whether verification or tests were skipped200 201Keep the chat summary shorter than the report itself.202