--- name: lingtai-ai/dev-guide-pr-review-deliverables source: https://app.decimal.ai/s/lingtai-ai-dev-guide-pr-review-deliverables@1/SKILL.md source_sha256: ee6be2a90af8 --- # PR Review & Deliverables Nested lingtai-dev-guide reference. Read this after the top-level router sends you here to prepare a PR for review, build its human-facing explainer, and run review gates before asking for a merge. It consolidates the PR-review-gate, HTML-explainer, deliverable-template, and release-style-audit practices, covering *preparing and reviewing* PRs and their human deliverables. Release publication is outside this bundled guide — use the dedicated release owner available in the maintainer's environment. ## Core principle A PR is review-ready only when (1) the diff is clean and validated, (2) a self-contained HTML explainer tells the human the story, and (3) the change has passed at least one independent review pass. Opening, editing, and merging PRs are external side effects: do them only after an explicit maintainer authorization for *that* side effect. ## 1. PR readiness gate - [ ] Clean diff: `git diff --check` (no trailing whitespace / conflict markers). - [ ] Targeted tests for the changed area pass; record commands and results. - [ ] If you touched utility/dev-guide skills, the nested-reference tests and the root router catalog/routing table were updated in the **same commit**. - [ ] Anatomy travels with code: any moved/renamed/split file cited by an `ANATOMY.md` is updated in the same commit. - [ ] No secrets, tokens, or private absolute paths in the diff or the explainer. - [ ] A self-contained HTML explainer exists (see §3). Known repo pitfalls: `docs/stars/stars.csv` may use CRLF intentionally — do not "normalize" it; and portal tests may need frontend assets built first (`npm --prefix portal/web run build`). ## 2. Independent review passes (gates, not permission) Run at least one independent, **read-only** review pass before merge. Strongest first: 1. **Multi-model / daemon review.** Generate a diff prompt and have a read-only daemon (Claude Code / Codex) or a second model review correctness, scope, and regressions. Save the review as an artifact so it is auditable. Run API-backed reviewers with keys from the environment (``), never inline. 2. **Claude review gate.** A focused Claude Code review of the diff for correctness bugs and reuse/simplification cleanups. 3. **Self review against the readiness gate (§1).** Treat each review as input, not a verdict: read the diff yourself (it is ground truth, not the daemon's summary), classify each finding (confirmed defect, edge risk, future refactor, doc/process note), and fix the smallest thing that resolves a real defect. Do not expand into a broad refactor because nearby code is related. These reviews are **gates, not authorization to merge** — see §5. ## 3. Self-contained local HTML explainer Every non-trivial PR ships one self-contained `.html` explainer for the human. This is the canonical statement of the requirement; other dev-guide references point here rather than restating it. **Local-only by default.** Routine PR explainers are local output, not repo artifacts. Write to an ignored location — `artifacts/pr--explainer.html`, `reports/pr--explainer.html`, `tmp/-.html`, or the agent/worktree report workspace — and hand the human the absolute `file://`-openable path in the short pointer message. Do **not** commit routine explainers. Commit one only when the human explicitly asks, when it is a release/long-term reference artifact, or when repo documentation links to it deliberately; use `git add -f` for that exception and explain the reason in the PR. **Naming and timing.** Name it `pr--explainer.html` once the PR exists; pre-push use `-.html` and rename locally after. Write it **before** asking for review or merge, and refresh it when blockers or fixes materially change the story. **Required sections**, in order: TL;DR / conclusion-first, baseline, what-was-done (with diff snippets), validation (commands + results), risks/decisions, next steps, and a source index. Plain text/Markdown is reserved for the short pointer message and conversational replies. **The only exception** is a strictly one-line docs/chore PR where the human has explicitly waived the report. Absent that waiver, write the HTML even for a small fix; if a change is too small for a useful explainer, that is a signal to bundle it with related work. ### Deliverable hygiene (any human-facing HTML) - **Conclusion first**, then evidence. Label every nontrivial claim with its source (file path, command, commit SHA, PR/issue number). - **De-private.** Repo-relative paths and generic placeholders (``); redact tokens/keys/chat IDs as ``. - **Self-contained & valid.** Single file, inline CSS, no remote assets, no build step. Sanity-check the markup before handing it over so a malformed tag does not silently swallow content. For the HTML skeleton, MathJax setup, and the full validation checklist, read `~/.lingtai-tui/utilities/swiss-knife/reference/html-report/SKILL.md` (or load the `swiss-knife` skill and route to `html-report`) — it owns those mechanics. The PR-specific path, naming, and section rules above still govern. ## 4. PR body hygiene and `gh pr edit` The PR body cites the issue, summarizes the change, and lists validation steps, mirroring the explainer's TL;DR and validation without duplicating the whole HTML. Keep body and explainer in sync when fixes land. `gh pr edit` can emit GraphQL deprecation warnings on some `gh` versions — those are warnings, not failures. If `gh pr edit --body-file` is noisy, re-run or set the body via the web UI; treat it as a version-dependent troubleshooting note, not a blocker. ## 5. Maintainer authorization boundaries Do not, without an explicit imperative authorization for that specific side effect: - open or merge PRs, push commits, or force-push; - file/close issues, close/delete branches or other resources; - edit a PR body on the remote. Generating diffs, running read-only reviews, and writing local explainers are always allowed. When approval wording is ambiguous, show the maintainer the final candidate refs/diff and ask before mutating GitHub state. For consequential releases (tagging, publishing to PyPI/Homebrew, website release archive/blog), use the maintainer environment's dedicated release owner; this reference grants no publication authority. ## Related references - `reference/contributing/SKILL.md` — issue → worktree → PR → merge loop and daemon decomposition. - `reference/skill-stewardship/SKILL.md` — PR-ready cleanup when the change adds or edits a skill. - `skills-manual` — generic skill authoring (when the deliverable is a skill).