- name
SKILL.md
Beceri dosyası yayıncının deposunda kalır.
Kopyalanan komutu bir terminale yapıştırın. Bu SKILL.md dosyasını ilgili ajana kurar.
npx skills add phuryn/product-engineering --skill independent-review -a cursor -yKopyalanan komutu bir terminale yapıştırın. Bu SKILL.md dosyasını ilgili ajana kurar.
npx skills add phuryn/product-engineering --skill independent-review -a claude-code -yKopyalanan komutu bir terminale yapıştırın. Bu SKILL.md dosyasını ilgili ajana kurar.
npx skills add phuryn/product-engineering --skill independent-review -a codex -yKopyalanan komutu bir terminale yapıştırın. Bu SKILL.md dosyasını ilgili ajana kurar.
npx skills add phuryn/product-engineering --skill independent-review -a grok -yKopyalanan mesajı bir Grok Bot sohbetinde gönderin. Bot bu SKILL.md dosyasını GitHub'dan alır ve tüm Bot'larınızın paylaştığı becerilere ekler.
Install this skill: https://github.com/phuryn/product-engineering/tree/HEAD/ai-shipping/skills/independent-reviewYayıncıdan
The session that wrote the code never clears it. A fresh reviewer that never saw the build reads the change for what would block or break it. That separation applies at every size: a one-line fix that ships gets a short round, never no round. Inside a phase, it joins the phase's series (§ When).
The tool is optional; the review is not. The wrapper in this skill's scripts/ picks the reviewer by default. Run python <skill dir>/scripts/review.py --check to see which. Its defaults are:
grok inspect and prints it for the report. In a trusted folder, that includes project instructions and a gitignored CLAUDE.local.md. A review worktree of the snapshot does not hold that file.CODEX_HOME AGENTS.md, bundled skills, agent tools and administrator additions remain; name them in the report (codex-agents § Reviewer lists the boundaries).Never use the building thread, resumed or forked, or a subagent of it. The reviewer must not inherit the builder's beliefs.
A fresh session of the builder's own model is independent: it never saw the build. It shares more blind spots than another family would. Accept that cost: a round that runs beats one skipped.
Everything below holds whichever reviewer runs. These are defaults, not the method. Grok, Claude Code and Codex can each review; apply grok-agents, claude-agents or codex-agents for driving them from another agent.
The repository's own instructions come first. Follow its agent instructions or release docs for reviewer, fallback, review bar, required moments and release range. They may also name the test gate and where deferred findings go.
a repository ranks its reviewers; it cannot rule out a review. When none of its named reviewers can run, use the wrapper's reviewer without asking. If no other family can run, use a fresh session of the builder's family. Never use the building session or skip review. Interpret "a model never reviews its own family's work" as "prefer another family". Apply agent-instructions to rewrite it accordingly and record owner choices and their precedence.
Apply one bar to every reviewer, including a repository's named reviewer. Require a fresh session that never saw the build, never a resume, fork or subagent of it. Use read-only tools only, no MCP servers or connectors, memory off, and the highest effort. Switch off project and user instructions where the CLI allows. Name everything that cannot be switched off in the round's report.
A sandbox flag alone is insufficient. In Codex, -s read-only binds only shell commands; user configuration can add tools acting outside it (Codex CLI 0.159.0, observed 2026-10-29). Ignoring user config does not remove connected apps, plugins or web search (Codex CLI 0.166.0, observed 2026-11-14). Leave that configuration out and switch those features off by name; apply codex-agents § Reviewer.
When a named reviewer cannot meet that bar, use the product's recorded fallback if it can, without asking. Otherwise use the fallback above, without asking. Name the actual reviewer and why it replaced the named one in the report. Where repository instructions say nothing, use these defaults. Ask when a default needs an owner-only fact, such as the released branch or last release.
Verify findings yourself, and after every fix rerun the tests it touches yourself. Run the full gate on the finished phase or standalone change, then follow § When before fresh review. Verify every finding against the code yourself, then fix what the bar names. Rerun each fix's regression test and the tests it touches yourself, then get a fresh review of the changed state. Repeat until the bar holds. Rerun the full gate on the cleared state when a fix followed its last full run, before that state is pushed or called done. If that gate fails, its fix is new code and gets a round. A gate that takes a couple of minutes can simply run after every fix.
Treat findings and their severity labels as claims, not results. Triage below is mandatory; it is the part that most often goes wrong.
git remote get-url --push --all origin | sed -E 's#//[^/@]*@#//#' must name that repository. The sed removes any username or token. If any URL differs, push nothing and ask.document-app check.ui-design visual checks to those screens, including walkthrough, rendered pass, screenshot critique and scored audit where required. Fix visual defects before starting the review series. Apply document-app in check mode, then repeat fresh review rounds until the bar holds; list Lows rather than fixing them. If any fix followed the last full gate, rerun it on the cleared state. Any resulting fix needs another fresh round. Where the branch deploys, its phase-ending push closes the series; then offer the owner a preview. Before hosting, keep the state local or push a branch that does not deploy, and preview through development.Compute the subject from git, covering the whole phase or unreleased range. A prose description can leave an unapplied migration or untracked file unreviewed. A phase's first round starts at the last commit a round cleared, or at the work's first commit when none has. It takes everything from there, plus the working tree. Before a release, round 1 takes everything unreleased, committed or not: last release to HEAD, plus the working tree.
git log --oneline $RELEASED..HEAD # the unreleased commits
git diff $RELEASED...HEAD --stat # its shape
git status --porcelain -uall # and anything uncommitted, file by file
Read that status for what does not belong, too. The wrapper inlines every untracked file under 200 KB, including its content. The cap is per file. A directory of small generated files therefore goes in whole: copied data, fixtures, scratch output or build artefacts without ignore rules. The turn cap rises to fit it. For anything outside the change, delete only what this session generated; otherwise .gitignore it or ask the owner before the round. A subject much longer than the diff's --stat suggests usually signals this. The wrapper warns when untracked files add more than 20,000 lines or most of a subject over 5,000, and never refuses.
Use the repository's last released state as $RELEASED. It may be production branch origin/<prod>, a release tag or the deployed commit.
Before the first release, review the whole history with --subject HEAD. Earlier phase series cover their phases; they do not replace this whole-product review. The wrapper writes every commit's author and message, every file HEAD holds, and every line its history removed. Include the first commit: a push sends every commit, and <first commit>..HEAD would omit it. A clone or fork whose history began in another repository uses the same --subject HEAD. The source repository's tags and branches are not this product's releases. Before any release, nothing is live yet. The brief therefore marks every finding INTRODUCED, including code that came with the history.
Never narrow the range by hand to make it fit. A release's first round includes already-pushed code: when pushes deploy, that code is exactly what users run. A range too large for one round is split, never shortened, in one of two ways:
Narrow every later round to commits since the previous round. Give the remaining unreleased range as context to read for interactions. Naming new code is scoping, not steering. Re-reviewing cleared code adds time and pre-existing noise while burying new findings. Passes find bugs, so cheap rounds beat thorough ones.
Bring old code into scope only where the change makes it newly reachable or newly wrong. Say this explicitly in the brief; interactions hold serious findings. Keep both kinds of pass: a whole-range review sees composition that per-commit rounds cannot.
Keep coordinator notes out of the review subject until its series closes. Suspected defects and running triage steer a fresh reviewer. Commit those notes only after the series' final code-clearing round, or keep them outside the repository until the series closes.
Scope the subject by what a reviewer must read, not by file count, and keep generated prose out of it. Give generated docs as context for code questions, not review subject; prose can exhaust a round that fits the code and tests.
Use the wrapper to apply review flags and reject short failed rounds. It picks the reviewer and fails loudly when output is too short to show a round ran:
S="<a scratch directory>"
python <skill dir>/scripts/review.py \
--brief "$S/review-NNN-brief.md" --cwd <repo> \
--subject "<range>" --out "$S/review-NNN.md" < /dev/null
echo "exit=$?" # 2: failed round (length or Codex event checks); 3: the reviewer is out of usage
With --out, Codex also saves <out>.events.jsonl, recording what the reviewer read and ran; treat it like the report and never commit it.
--subject takes a git range: <sha>^! for one commit or HEAD before the first release. The wrapper refuses an empty subject, a range without a start, or one with no commits and a clean tree. Grok and Claude Code have no shell; Codex has a read-only shell. The wrapper writes the range's log and diffs, then everything uncommitted, to a never-committed file inside the git directory. It lists untracked files individually, with their content. It gives the reviewer the length and paging instructions: some file tools return at most 1,000 lines and may not say there are more. For Grok, it raises the turn cap when paging the subject needs more turns. The Codex and Claude Code runs have no turn cap; --max-turns does not apply to them.
A range that contains a merge also carries the range's cumulative diff. git log -p shows merge commits without their diffs, omitting conflict resolutions or edits inside merges. The wrapper adds the cumulative diff for A..B and <sha>^!. A bare ref such as HEAD needs none: its subject includes every held file and every line removed in history. It warns on any other range shape. Each commit's change appears again, nearly doubling the subject; size the round accordingly.
Use the repository's runnable fallback when the default reviewer cannot run. --reviewer auto, the default, takes the first installed of Grok, Codex and Claude Code; --reviewer grok, codex or claude forces one. Codex runs exec --json --ephemeral --ignore-user-config --ignore-rules -s read-only --disable apps --disable plugins --disable tool_suggest --disable image_generation --disable memories --disable hooks -c web_search=disabled. It passes --effort as model_reasoning_effort (xhigh by default). Its event stream fails a round with no successful command, a completed outside MCP call, a web search, completed file changes, a missing report or events, or a failed turn. Pass --model to choose its model: ignoring user config also omits your configured model. On Windows, --windows-sandbox elevated|unelevated explicitly overrides the mode; absent that flag, the wrapper restores [windows].sandbox from config. It stops with setup instructions when neither supplies a mode (observed 2026-11-16, Codex CLI 0.169.0). Claude runs claude -p with --restricted, --tools Read,Grep,Glob, --strict-mcp-config, --no-session-persistence, --effort max and CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Measured on 2026-10-10: without that variable, a headless session loads the project's memory index holding builder notes. With these flags, no project instructions, personal notes, memory or skills list was in its context.
An installed reviewer can still be out of usage. The wrapper then exits 3 and prints the same round with the next installed reviewer. After Grok that is Codex, or Claude Code without Codex; after Codex, Claude Code, or Grok without Claude Code; after Claude Code, Grok, or Codex without Grok. With no other installed, it prints the --subject-only route. Run the repository's recorded fallback if it can run, including its model. Otherwise run the wrapper's fallback without asking, even if the repository names only the reviewer that ran out. If no other family can run, use a fresh session of the builder's family. Record the actual reviewer and reason (§ Apply one bar to every reviewer, including a repository's named reviewer).
With none of the three CLIs, give the wrapper's prompt to a fresh separate process. Use --subject-only with --brief, --cwd and --subject as above. It writes the subject and prompt into the git directory and prints their paths. The prompt contains the brief plus paging instructions. Give it to a fresh read-only session of your agent, started as a separate process in the checkout under review. Never use a subagent, fork or resumed session of this one. Require read-only tools, no MCP servers or connectors, the highest available reasoning effort, and memory off where it allows. Switch off project and personal instructions where allowed. In a review worktree, the git directory is outside the checkout; give read access there, never write.
Where no fresh session can be started, stop and hand the owner the prompt path. The round has not run until a fresh session answers. A short clean answer fails the round. Delete both files when the round ends.
Apply the CLI's skill when running a reviewer by hand. Apply grok-agents for the bare Grok call and each wrapper flag's purpose. Apply codex-agents § Reviewer for the Codex command the wrapper runs and its manual checks. These facts hold whichever reviewer runs:
--always-approve, can exit 0 after a sentence of preamble. That reads like "found nothing". A genuinely empty round argues its way there over paragraphs. Require it to say what it read, what it expected to find and why it holds. The wrapper fails output under 1,500 characters with exit 2; measure a manual round the same way.< /dev/null when the CLI takes the prompt through a file flag. When it reads stdin, as Codex does, pass the prompt file itself. Never leave stdin waiting on a terminal: that hangs without output. Long inline prompts trip permission classifiers.A round can fail by running out of room, leaving the same short output. Read its log. Memory flushes distinguish context exhaustion from a reviewer that read nothing. Split a large phase subject by its stages' commits or area; never shorten the range. Keep and verify findings emitted before failure.
Run the closing series beside the next phase in its own checkout. An optional advisory stage round uses the same isolation and clears nothing. Their safe overlap depends on the checkout, not the commit.
Commit means "reviewed from here". Push means "this round is closed". Local history is working state; a deploying branch receives only the state a closing series cleared. Advisory stage rounds clear nothing; before hosting, a phase can remain local. A production push remains a release and requires the owner's go.
# 1. tests green on your own run, then freeze the subject
git add -A && git commit -F - # the snapshot the round reviews
SNAP=$(git rev-parse HEAD)
# 2. give the reviewer its own checkout of that exact commit, under a name no other
# session on this machine is using (`git worktree list` shows the taken ones)
git worktree add ../<repo>-review-<phase> "$SNAP"
# 3. review there while the next phase builds in the main tree. In the worktree the
# range ends at HEAD, the snapshot ($RELEASED..HEAD, <last round>..HEAD), never at
# a branch name, which moves as the next phase commits
python <skill dir>/scripts/review.py \
--brief "$S/review-NNN-brief.md" --cwd ../<repo>-review-<phase> --subject "<range>" ...
# 4. when a round closes with no INTRODUCED finding above Low and no High or Critical
# of any age, push the snapshot THAT round reviewed — never the branch tip, which may hold the next phase's commits.
# If a fix followed the last full gate run, the full gate passes on that snapshot first, in a
# checkout of it when the main tree has moved on.
# A round that found anything the bar names is fixed, re-tested, re-snapshotted and reviewed again;
# SNAP is read from that round's worktree, whose HEAD is the snapshot it reviewed
# (a new shell has lost it, and the main tree's HEAD may hold the next phase); `:?`
# refuses an empty one, which would turn the push into a delete. The first push goes
# only where the owner named (§ When)
SNAP=$(git -C ../<repo>-review-<phase> rev-parse --verify HEAD)
git push --no-follow-tags origin "${SNAP:?}:refs/heads/<branch>"
# (if you linked node_modules into the worktree, delete that link first; see below)
git worktree remove ../<repo>-review-<phase>
Never remove a worktree whose node_modules links to another checkout. The reviewer only reads, so its worktree needs no node_modules. A linked one may support typechecks, unit tests or builds: a Windows junction or a symlink elsewhere. git worktree remove --force deletes through that link, emptying the main checkout's node_modules. A running gate or dev server dies; the next run fails with 'playwright' is not recognized. Remove the link itself first. On Windows, cmd /c rmdir <worktree>\node_modules removes a junction without touching its target. Elsewhere, use rm <worktree>/node_modules without -r, then remove the worktree. Alternatively, give the worktree its own npm ci, which next build needs anyway.
Push the snapshot, not the branch. Once pushes deploy, the branch tip can ship unreviewed commits made by the next phase during review. Those commits belong to the next round's subject.
The worktree is the load-bearing part. Committing alone isolates nothing. The reviewer deliberately reads the working tree and diff because a diff cannot show interactions. Pointing it at the builder's tree produces findings about half-written code that no longer exists that way.
A push can have side effects beyond the deploy. An integration may apply migrations, or a hook may publish. Complete prerequisites before pushing, such as applying and verifying migrations by hand, so the push finds nothing pending. A production migration also waits for the owner's go; apply release-gate. Keep files you do not intend to run out of any integration's pickup location.
the whole-range round before a release still runs against a still tree. Parallel review finds issues against code that has moved; fixes land on a changed tree. A structural finding can cost the newer work. That trade is fair at a phase boundary with a settled foundation, never at the end. The whole-range round must see everything together.
Write only these five parts, in this order, to avoid steering.
file:line evidence, what to change. Keep it terse, without praise, ranked. End with those most likely to bite.Do not include earlier findings, suspected files, your argument for the design, or a request for approval. A reviewer asked whether it approves will tell you it approves.
Question zero, before any other: say in ONE SENTENCE what actually goes wrong for the person. If it does not sound bad read aloud, there is nothing to fix. "You land on one of your own items that a filter was hiding" dies unaided. The reviewer's severity label is part of its claim, and taking one at face value is how a clean release grows two invented P1s.
does anything cross a line the person cares about? Examples are another tenant's data, private data on a public surface, another user's private content, disappearing work, lost writes or anonymous access to a member capability. If everything already belongs to the person and stays visible, it is a surprise; a surprise is polish. Distrust a real mechanism with a scary label and speculative harm. Ask whether the person can see where they are. Builder reports and reviewer priorities are both claims; neither model decides.
Require literal steps, permitted execution and a person with a reason. A finding that cannot answer these three questions is not a finding:
A layout or performance claim is settled on the running build, not by re-reading the file — in either direction. Stylesheet arithmetic may be right while the conclusion is false. A flex item's automatic minimum is its content; cells wider on paper than their container can shrink rather than overflow. "Obviously it shrinks" is as speculative as "obviously it overflows": measure before accepting or rejecting. Measure visible text against neighbours in the same column, not the named container. The defect itself can produce matching box edges. Measure performance on both builds, with the baseline built from HEAD in its own worktree. Let the numbers retire the fix.
When findings cluster, look for one false premise underneath before fixing any of them.
Rank by what it costs this product, not by where it sits in the list. Read user and business impact: who sees it, how many and at what moment. A widely seen instruction failing at a critical moment can cost more than its mechanism suggests. A recoverable flow one admin meets once can cost less than its label. When a rule hides information from product users, grade further probes by harm to an honest user. A probe usable only by someone deliberately defeating their own measurement is Low. They hide information from themselves, then seek it out.
A fix has a price, and the price compounds. A confirmed defect is still a decision. Watch for rounds getting narrower, each trigger needing more actors or more precise interleaving. That finds what code permits rather than what users hit. Ask aloud what the fix costs to understand next year, by someone who was not here. State the residue's price plainly. If acceptable, write that down and stop. Ask whether the fix replaces a mechanism or adds one. Replacement is usually right; a special case per round compounds the problem.
Accepting a finding is a legitimate outcome. A rarely-wrong rule somebody can hold in their head beats an always-right one nobody can.
A fix that did not need to happen is itself a defect. Weigh branches, permanent complexity and new review surface against the occasional actual harm. Run the fix's regression test on the tree before the fix. If it passes, the finding was false: revert the fix and keep the assertion. Apply test-harness for that rule.
Prefer removing the rare case to supporting it. Constrain input, refuse the state, drop the option or choose a default that cannot produce it. An unreachable case needs no code, test or comment and cannot interact with the next fix. Ask whether it must exist before writing its branch. Only then weigh fixing against accepting the residue.
Beware the fix that opens a door. Two conditions right alone can be wrong together. Continue the loop past the fix that felt final.
Fix the class, not the instance. When a finding resembles an earlier one, say so in the next brief and ask for the audit.
When a repair writes a field that says who decided, scope it by the subject (this participant, this item), never by the rows' current state. A state filter skips exactly the rows another actor already decided.
When the actor is an attacker, ask whether the finding adds a capability the attacker does not already have in that position. A mechanism granting nothing new is a description, not a vulnerability; question 2 above passes too easily here. Watch for reasoning from one entry point without reading neighbouring rows in the permission table.
Improve the average; the exception is the person's work. Polish serves the case most people meet, letting the rest degrade honestly with geometry intact. Use a same-size placeholder so nothing jumps when the real thing arrives. Anything losing or duplicating what a person made gets full treatment, however rare.
Say it plainly when a round is empty after triage. "Three findings, none survive the usage model" is a result, expected on a well-built change.
Read a clean round's argument, not only its verdict. Code cited to prove safety can expose the same defect one surface over.
When a round changes one user-facing sentence, read its neighbours and the assertions around its pin. A repair can distract from a nearby claim it just made false.
Search every doc when a state they all describe changes. When production exists or a feature goes live, find old-state phrases and fix them in one pass. Do not stop at the line the round named. When a rule is repealed, find sentences that argued for it: comments, fixtures and doc paragraphs. Ask what each still holds up.
Repair a drifted pair by copying the sentence that is right into the place that is wrong. Never write a third version; pin their agreement in the same change.
When a repair delegates behaviour to the platform, enumerate what the old code decided. A deleted handler takes its judgement with it; the diff shows only deletion. When replacing a control, inspect its odd attributes: aria-disabled where disabled would do, or a seemingly redundant handler. Grep deleted lines for the comment arguing for them.
Stop at no INTRODUCED finding above Low and no High or Critical of any age. Fix High and Critical now, regardless of age. Small releases reach that bar fastest; later releases review only their own commits.
A Low goes to the owner's list, not into the loop. An introduced Low needs no fix and opens no round. Record it with its round number where pre-existing findings are recorded, and name it in the summary to the owner. Fix one only in a batch that already needs another round, or when the owner asks. Any fix is new code and gets a round.
When one mechanism draws findings two rounds running, stop patching it. Repeated inverse defects in one area mean the design is wrong. Before the next round, choose one option in writing:
Scale this by whether the work was requested. Apply it hardest to unrequested hardening, lightest to a feature the owner asked for by name.
Budget for a fix commit's own round in ingest, queue and concurrency code. When planning, allow for that tendency.
Record pre-existing findings with their deferral reason and a revisit trigger. Include the trigger because it is what gets the finding fixed. Use the repository's backlog file or issue tracker; ask if it names none. High and Critical are the exception: fix them now, regardless of age. Never silently drop a finding. The release summary states each round's finding count and what happened to each, including those not worth fixing and why.
Number rounds in one sequence per repository. Cite the number wherever the outcome lands: fix commit, backlog row, merge and release record.
Verify every finding against code by hand before acting. Cited line numbers are claims too. Rerun the tests the fix touches yourself after every fix; "it says it passes" is a claim, never a result. Record disproved findings as wrong beside confirmed ones, making the next round's hit rate legible.
Each rule's origin, the case that taught it, is in receipts.md beside this file; read it when a rule's edge is unclear.
The last round came from a fresh reviewer given only the mechanical range and found no introduced finding above Low, with nothing fixed after it. No High or Critical of any age is open; every earlier finding was checked against code before being fixed or dismissed, and accepted Lows are recorded.
Bring in a peer early for design or arguing a decision through. Apply codex-agents, claude-agents or grok-agents; this skill reviews what was built.
Use the related skills for CLI mechanics, delegation and reading defects. Apply those three skills to drive Grok, Claude Code or Codex from another agent in any role, including reviewer. Apply delegation for briefing and verifying any delegate, and code-review for reading code for defects.
Before 'ship it', a deploy or release, for 'an independent review', and after each fix until a round is clean: a fresh reviewer that never saw the build.
---name: independent-reviewdescription: Before 'ship it', a deploy or release, for 'an independent review', and after each fix until a round is clean…---# ai-shipping/skills/independent-review/SKILL.mdSSS
ai-shipping/skills/independent-review/SKILL.md dosyasını yayıncıdan indirin veya yolu kopyalayıp depoyu açın. PlugMCP beceriyi listeler, dosyayı barındırmaz.
Yayıncı bunu şurada tutuyor: https://github.com/phuryn/product-engineering.
Claude, Cursor, Codex ve Grok Build, yayıncının deposundan eklediğiniz bir SKILL.md dosyasını okuyabilir. Grok Bot, becerinin GitHub klasör bağlantısını bir sohbette gönderdiğinizde onu kurar.