Encode review practices mined from apify-core/worker/crawlee PR feedback#13
Draft
jirispilka wants to merge 1 commit into
Draft
Encode review practices mined from apify-core/worker/crawlee PR feedback#13jirispilka wants to merge 1 commit into
jirispilka wants to merge 1 commit into
Conversation
Mined ~790 review threads across 56 discussion-heavy PRs in apify-core, apify-worker, crawlee, and crawlee-python, cross-referenced against this repo's open issues/PRs (#7-#12) to avoid duplication, and folded in published loop-design guidance (judge self-preference bias, evidence- grounded critique). New rules cover only gaps not already raised: - Standing checks grow from three to six: evidence-grounded findings (unverifiable suspicion is a question, not a finding; referenced identifiers must exist), public-surface minimality (new exports need a consumer or a visibility reason), and doc sync for public changes (README/guides/upgrading notes updated in the same diff). - Implementer: diff stays scoped to the design (incidental hunks are reverted or get a one-line rationale in claim.md); non-obvious mechanisms, suppressions, and magic constants get why-comments. - Architect: search before inventing (name the existing helpers the design builds on); multi-step writes state failure ordering in Risks. - Model tiering: the review panel never resolves entirely onto the implementer's model (self-preference bias). - Finish: PR body scales with the diff — mechanism and known limitations for large changes, one-line whys for incidental ones. Each rule is pinned by a contract test; SKILL.md stays at 444/450 lines. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016G4uCkx2btpqfGtJRAPJKd
jirispilka
marked this pull request as draft
July 18, 2026 08:03
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What we're solving
Shepherd's pipeline misses several finding classes that human reviewers raise over and over in the repos it serves. We mined 56 discussion-heavy PRs (~790 review threads) across apify-core, apify-worker, crawlee, and crawlee-python, cross-referenced everything against this repo's open work (#7, #11, and issues #9/#10) to avoid duplication, and folded in published loop-design guidance (LLM-judge self-preference bias, evidence-grounded critique). This PR encodes only the gaps not already covered by open PRs/issues.
How
@internal, private); ~25 mined threads.claim.md; non-obvious mechanisms, suppressions, and magic constants get why-comments (the single largest mined category, ~70 threads across all four repos).Each rule is pinned by a contract test; 92 tests pass; SKILL.md at 444/450 lines.
Alternatives considered
Notes
SKILL.mdconflicts with both (same standing-checks paragraph and step 9), the test file only with feat: Add scope split, followups stage, and detection standing checks #11. Whichever lands last does a small reconcile — the standing checks fold into one list, and feat: Tighten reviewer standing checks, design Q&A, and PR body rules #7's PR-body brevity cap composes with this PR's body-scaling rule (brief by default, mechanism + limitations for large diffs).🤖 Generated with Claude Code
https://claude.ai/code/session_016G4uCkx2btpqfGtJRAPJKd
Generated by Claude Code