From faa88ba929313db52fb6f42985b1350dd4184672 Mon Sep 17 00:00:00 2001 From: Phelan164 Date: Mon, 14 Sep 2026 12:21:14 +0700 Subject: [PATCH] feat(skills): add optional independent engineering review --- AGENTS.md | 5 ++ examples/templates/measured-task-receipt.md | 41 ++++++++++ skills/engineering-loop/SKILL.md | 3 + .../references/independent-review.md | 78 +++++++++++++++++++ .../references/loop-contract.md | 2 + 5 files changed, 129 insertions(+) create mode 100644 skills/engineering-loop/references/independent-review.md diff --git a/AGENTS.md b/AGENTS.md index dc8716b..25c2f41 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,11 @@ Maintain an accurate, engineering-first learning guide for OpenAI Codex. - Treat wiki queries as read-only unless the user explicitly requests capture, ingest, archive, or promotion. +## Pull requests + +This personal open-source repository does not require Jira tickets. Use a +descriptive branch and PR title; link relevant GitHub issues when applicable. + ## Validation Run: diff --git a/examples/templates/measured-task-receipt.md b/examples/templates/measured-task-receipt.md index 0500fea..fc9097e 100644 --- a/examples/templates/measured-task-receipt.md +++ b/examples/templates/measured-task-receipt.md @@ -94,3 +94,44 @@ run record, not a universal productivity score. For a stopped or resumed run, add a compact checkpoint under `evidence` with confirmed facts, disproved hypotheses, the current diff, budget remaining, and the next evidence-producing action. Do not copy the full transcript. + +## Optional independent review + +When a separate reviewer participates, add this section to the receipt. Use +one entry per attempt, including attempts that fail or stop before a verdict. + +```yaml +independent_review: + attempts: + - reviewer_id: + model: + context_separation: # fresh, inherited, or unknown + base_revision: + reviewed_revision: + status: # completed, failed, or stopped + findings: + - id: + disposition: # confirmed, rejected, duplicate, or unresolved + validated_by: # builder, test, human, or unresolved + evidence: + elapsed_seconds: + total_tokens: + total_cost_usd: + human_adjudication_seconds: + final_candidate_revision: + last_reviewed_revision: + uncovered_changes: [] +``` + +An empty `findings` list means no findings were recorded; check `status` before +interpreting it. Record zero only when observed, and leave unavailable numeric +values blank. A requested skill or role is not evidence that a review ran. + +Review tokens and cost are components of the overall `outcome` totals, not +additional amounts to add again. Concurrent review durations must not be +summed into task wall time. Report partial telemetry coverage in +`evidence.unverified`; do not present a known subtotal as a complete total. + +Revision equality alone is insufficient for a dirty working tree. Record an +immutable snapshot identifier when uncommitted changes are reviewed. Any later +edit makes prior review evidence stale for that candidate. diff --git a/skills/engineering-loop/SKILL.md b/skills/engineering-loop/SKILL.md index 8239833..fe21c8c 100644 --- a/skills/engineering-loop/SKILL.md +++ b/skills/engineering-loop/SKILL.md @@ -30,6 +30,9 @@ explicit retry, time, token, or cost limit, also use When a defect is intermittent, performance-related, difficult to reproduce, or resists the first evidence-driven pass, use [references/hard-debugging.md](references/hard-debugging.md). +For complex or higher-risk changes where independent coverage is useful, or +when the user requests a separate reviewer, use +[references/independent-review.md](references/independent-review.md). ## Run the loop diff --git a/skills/engineering-loop/references/independent-review.md b/skills/engineering-loop/references/independent-review.md new file mode 100644 index 0000000..1a7be65 --- /dev/null +++ b/skills/engineering-loop/references/independent-review.md @@ -0,0 +1,78 @@ +# Independent review + +Use a separate reviewer when requested or when a complex change, authorization +boundary, migration, or data-integrity risk warrants additional coverage. +Keep self-review and relevant checks sufficient for ordinary small changes +unless repository policy requires more. Delegation must be available and +authorized; otherwise report the missing review and follow the task's existing +completion requirements. + +## Separate the context + +A fresh session using the same model can provide a separate review perspective. +It does not provide model diversity or eliminate shared blind spots. A +different model or provider is optional, subject to availability and the +user's execution and data-sharing permissions. + +Give the reviewer a compact packet: + +```text +Requested behavior and acceptance criteria: +Applicable repository instructions: +Base revision: +Reviewed revision or immutable snapshot identifier: +Diff and relevant source/test access: +Commands already run and their actual outcomes: +Known unverified checks: +Review scope and explicit budget, if any: +``` + +Keep the builder's conversation, self-review, proposed verdict, and preferred +conclusions out of the packet. Supply required domain facts and source access +so independence does not become an under-informed review. A full-history fork +does not meet this context separation; use a fresh context when the host +supports one and report any unavoidable history inheritance. + +The reviewer must not edit the builder's files, commit, merge, or publish. +Use read-only access or an isolated checkout with no authority to change the +candidate. Tests that write temporary artifacts need an authorized disposable +environment. Do not keep changing the candidate while it is being reviewed. + +## Review and disposition + +Ask for actionable findings with file/line, violated requirement or failure +scenario, impact, and supporting evidence. Report uncertainty and missing +context explicitly. An empty findings list is not proof of correctness. + +The builder evaluates each finding as confirmed, rejected with evidence, +duplicate, or unresolved. Fix confirmed consequential defects, and run checks +affected by the fix. Do not accept a recommendation solely because another +agent made it. A material disagreement needs an additional probe or human +decision under the existing task contract. + +Record the exact revision reviewed. A new commit or working-tree edit makes +that verdict stale for the new candidate. Re-review the delta and affected +interactions; expand to the full diff when the fix changes broad assumptions. +The final handoff names the last reviewed revision and any uncovered changes. +Review completion grants no merge authority. + +## Measure whether it helped + +Use the optional independent-review section of the measured task receipt. +Record reviewer identity/model, context separation, revisions, finding +dispositions, elapsed time, reported tokens/cost, and human adjudication time. +Count all review attempts, including failed or abandoned ones. Keep unavailable +values unknown and include reviewer usage once in the overall task totals. + +Compare confirmed catches and reduced human correction against extra time, +tokens, and false alarms on comparable tasks. Label builder-confirmed findings +separately from test- or human-validated findings. Same-model independence and +review pass rates alone do not establish an efficiency or quality gain. + +## Inspiration + +Community workflow informed by Code Mower's +[independent, revision-bound review architecture](https://github.com/codemower-ai/code-mower/blob/ad4ba6129dc90922cba63e20ea0715e424356b79/docs/architecture.md) +and [reviewer calibration policy](https://github.com/codemower-ai/code-mower/blob/ad4ba6129dc90922cba63e20ea0715e424356b79/docs/lane-promotion-policy.md). +These are instructions and evidence conventions; runtime enforcement depends +on the host. No Code Mower installation is required. diff --git a/skills/engineering-loop/references/loop-contract.md b/skills/engineering-loop/references/loop-contract.md index b00c37b..67e0f24 100644 --- a/skills/engineering-loop/references/loop-contract.md +++ b/skills/engineering-loop/references/loop-contract.md @@ -115,6 +115,8 @@ Then check code quality: Use a fresh read-only reviewer for higher-risk changes when it adds independent coverage. Do not delegate a small diff merely to satisfy a process checklist. +Apply [independent-review.md](independent-review.md) for the review packet, +revision binding, finding disposition, and cost accounting. ## Stop decision