docs: require patch-backed regression provenance

[steipete]

What Problem This Solves

A blame result can identify a shallow or grafted history boundary rather than the commit that introduced a behavior. Treating that result as causation can incorrectly attribute a regression to a code author, PR author, merger, or committer.

This is the shared review-guidance companion to the provenance repair motivated by the Browser startup review. It does not change the Browser fix or the existing bot comment.

Why This Change Was Made

Require the actual parent-relative patch before saying introduced by. Raw Git parents must be inspected rather than inferred from git show, rev-list, a commit subject, or blame output. Boundary markers alone are not introduction proof; missing or unverifiable history remains unknown.

Keep code author, introducing PR author, merger, committer, automation trigger, and current PR author separate. Carried forward and made visible also require evidence. Unknown provenance does not invalidate an independently proven bug.

User Impact

Reviewers receive a more accurate attribution contract without changing review, publishing, or authorization commands. Documentation only; no runtime or dependency changes.

Evidence

• ruby scripts/validate-skills: 69 skills validated from this repository.
• git diff --check: passed before commit.
• Fresh independent Codex review through P2: scoped-clean, no findings.
• Git's raw-parent and boundary behavior was checked against upstream source and real disposable Git repositories during the owning provenance investigation.

The original review's raw blame stdout is not in the recovered evidence, so this change does not claim a specific historical checkout cause or assign a replacement introducer.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 29, 2026, 3:38 PM ET / 19:38 UTC.

ClawSweeper review

What this changes

The PR updates GitHub deep-review guidance to require parent-relative patch evidence before attributing a regression to a commit or person.

Merge readiness

⚠️ Ready for maintainer review - 2 items remain

Keep open for normal owner review: this draft is a narrow, internally consistent documentation clarification, and no blocking correctness or security issue was found.

Priority: P3
Reviewed head: f20b1b1f2d823742f30776af109060a7cb5e40df
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused documentation update with consistent policy wording and no blocking review findings.
Proof confidence	🌊 off-meta tidepool	Not applicable: All changed content is documentation guidance, so runtime behavior proof is not applicable.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: All changed content is documentation guidance, so runtime behavior proof is not applicable.
Evidence reviewed	4 items	Introduced documentation change: The full skill keeps the provenance section focused on bug and regression review, and the new text requires a raw-parent header plus a parent-relative diff before using causal attribution. Commit provenance: The proposed commit has the reviewed main revision as its sole raw parent, establishing that the inspected ten-line documentation delta is the PR-introduced change. Repository validation contract: The repository README identifies this file as a reusable skill and specifies scripts/validate-skills as the validation command after skill edits; the PR body reports that validation and the supplied checks show smoke passed.
Findings	None	None.
Security	None	None.

How this fits together

The GitHub deep-review skill guides reviewers investigating repository bugs and regressions. Its provenance guidance turns history inspection into reviewer-facing attribution conclusions.

flowchart LR
  A[Bug or regression report] --> B[Deep review skill]
  B --> C[History candidate search]
  C --> D[Raw parent and patch check]
  D --> E[Provenance conclusion]
  E --> F[Reviewer report]

Loading

Decision needed

Question	Recommendation
Should this owner-authored draft be marked ready for merge with the proposed provenance wording?	Keep draft pending owner confirmation: Leave the PR open until the owner confirms the final wording and marks it ready.

Why: The patch is technically sound, but it is an owner-authored draft and repository policy requires explicit maintainer judgment rather than automated closure or landing.

Before merge

• Complete next step (P2) - No repair is needed; the owner should confirm and mark the draft ready through normal PR review.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation scope	1 file changed; 5 added, 5 removed	The PR is limited to a single provenance-guidance section.

Technical review

Best possible solution:

Keep the stricter provenance wording as the skill’s review contract once its owner marks the draft ready.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR changes review documentation rather than a runtime behavior.

Is this the best way to solve the issue?

Yes: requiring direct parent-relative patch evidence is the narrowest maintainable way to prevent causal claims based solely on blame or shallow-history markers.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against 55a873525dad.

Labels

Label changes:

• add P3: This is a documentation-only review-guidance change with no runtime behavior change.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: All changed content is documentation guidance, so runtime behavior proof is not applicable.

Label justifications:

• P3: This is a documentation-only review-guidance change with no runtime behavior change.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: All changed content is documentation guidance, so runtime behavior proof is not applicable.

Evidence

What I checked:

• Introduced documentation change: The full skill keeps the provenance section focused on bug and regression review, and the new text requires a raw-parent header plus a parent-relative diff before using causal attribution. (skills/github-deep-review/SKILL.md:64, f20b1b1f2d82)
• Commit provenance: The proposed commit has the reviewed main revision as its sole raw parent, establishing that the inspected ten-line documentation delta is the PR-introduced change. (skills/github-deep-review/SKILL.md:64, f20b1b1f2d82)
• Repository validation contract: The repository README identifies this file as a reusable skill and specifies scripts/validate-skills as the validation command after skill edits; the PR body reports that validation and the supplied checks show smoke passed. (README.md:19, f20b1b1f2d82)
• Area history: Recent history for the affected skill is authored by Peter Steinberger, including the current documentation update and the preceding skill refactor. (skills/github-deep-review/SKILL.md:64, 1f53be0b2751)

Likely related people:

• steipete: Peter Steinberger authored the current change and the preceding documented history for this skill. (role: recent area contributor; confidence: high; commits: f20b1b1f2d82, 1f53be0b2751; files: skills/github-deep-review/SKILL.md)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.