Skip to content

moonlight-lupin/agent-skills / plugins/dev-pipeline/skills/review-lessons

review-lessons

Verified

Library of lessons from past build-review loops — not a stage. Use when a review or fix round hits a specific case: a reviewer BLOCKING that contradicts the brief, a test that passes but checks nothing, a feature dead in production, SQLite/WAL migrations, MCP tool surfaces, REST API authz, app ↔ external-source sync, Android/APK verification, fill-template extraction, CLI/git mechanics, reviewer outages. Load the one file the case needs; never load the whole library.

FileKindSize
SKILL.mdexecutableskill md5.5 KB
references/architecture-refactor-test-updates.mdexecutablescript2.9 KB
references/beta-gate-release-hardening.mdexecutablescript3.3 KB
references/ci-and-repo-hygiene.mdexecutablescript3.7 KB
references/confirm-loop-lessons.mdexecutablescript24.2 KB
references/cross-model-parallel-review.mdexecutablescript4.8 KB
references/data-integrity-principles.mdexecutablescript7.3 KB
references/delegate-skills-adaptation.mdexecutablescript2.1 KB
references/evidence-pairs.mdexecutablescript2.5 KB
references/extraction-from-filled-docs.mdexecutablescript6.1 KB
references/field-briefing-integration.mdexecutablescript5.2 KB
references/full-module-replacement-scoping.mdexecutablescript6.3 KB
references/generated-frontmatter-and-reviewer-outages.mdexecutablescript3.0 KB
references/loop-pitfalls.mdexecutablescript27.9 KB
references/mcp-category-tool-implementation.mdexecutablescript5.3 KB
references/mcp-design-review-patterns.mdexecutablescript5.7 KB
references/minified-bundle-selector-research.mdexecutablescript4.4 KB
references/mobile-app-verification.mdexecutablescript4.8 KB
references/multi-batch-sequencing.mdexecutablescript5.7 KB
references/parallel-dual-review.mdexecutablescript10.8 KB
references/pitfalls-dispatch-semantics.mdexecutablescript6.3 KB
references/pitfalls-fix-round-verification.mdexecutablescript6.6 KB
references/planning-with-files-adaptation.mdexecutablescript2.6 KB
references/plugin-gates-and-fix-rounds.mdexecutablescript8.2 KB
references/production-reachability-review.mdexecutablescript5.0 KB
references/reconciliation-review-findings.mdexecutablescript3.1 KB
references/rest-api-review-checklist.mdexecutablescript13.0 KB
references/review-findings-adjudication.mdexecutablescript34.4 KB
references/scope-test-in-process-execution.mdexecutablescript4.2 KB
references/security-property-tests.mdexecutablescript14.2 KB
references/sqlite-migration-pitfalls.mdexecutablescript4.1 KB
references/sqlite-wal-review-findings.mdexecutablescript5.0 KB
references/sync-pipeline-review-patterns.mdexecutablescript13.2 KB
references/tool-mechanics-pitfalls.mdexecutablescript44.1 KB
references/upgrade-path-test-pattern.mdexecutablescript3.0 KB
---
name: review-lessons
description: "Library of lessons from past build-review loops — not a stage. Use when a review or fix round hits a specific case: a reviewer BLOCKING that contradicts the brief, a test that passes but checks nothing, a feature dead in production, SQLite/WAL migrations, MCP tool surfaces, REST API authz, app ↔ external-source sync, Android/APK verification, fill-template extraction, CLI/git mechanics, reviewer outages. Load the one file the case needs; never load the whole library."
metadata:
  version: 1.0.0
  author: moonlight-lupin
  license: MIT
  platforms: [linux, macos, windows]
  hermes:
    tags: [lessons, review-findings, pitfalls, sqlite, mcp, rest-api, security-property-tests, data-integrity, test-quality, dev-pipeline]
    related_skills: [review-commit, build, test-evals]
---

# Review Lessons

What past loops taught, filed by case. The dev-pipeline's PROCESS lives in
the stage skills — round budgets, severity floor and stop conditions in
`review-commit/references/confirm-round-protocol.md`, model names in
`orchestrator/references/lanes.md`. Where a lesson here disagrees with those
files, they win: lessons are dated evidence, the protocol is the current rule.

**How to use:** find the case below, read that one file, apply it to the
finding in front of you. Don't preload — most of these are project-specific.

**Old names:** these files predate v0.2. "build-review-loop", "codex-confirm-loop"
and "subagent-driven-development" in them mean today's `review-commit` and
`build` stages; model names in them are what ran at the time, not current
pins. Numbered references ("pitfall #N", "rule #N") point at the retired v0.1
stage SKILL.md numbering, which no longer exists — treat them as historical
context, not as pointers to read.

## By case

### Adjudicating findings and fix rounds
| Case | File |
|---|---|
| Reviewer BLOCKING contradicts the dispatch spec or a contract test; deferred findings as design questions | `references/review-findings-adjudication.md` |
| Fix at the wrong layer, red-test triage, two-sided fixes, live verification | `references/pitfalls-fix-round-verification.md` |
| Builder self-report, regressions from fixes, mid-build user steers, brief races | `references/loop-pitfalls.md` |
| Confirm-loop probes: exact repro shapes, vacuous tests, mutation-testing a fix, race probes, kernel state | `references/confirm-loop-lessons.md` |
| Two reviewers in parallel, synthesizing their findings | `references/parallel-dual-review.md`, `references/cross-model-parallel-review.md` |
| A reviewer lane is down; YAML frontmatter generated by f-strings | `references/generated-frontmatter-and-reviewer-outages.md` |
| Plugin ship gates and fix-round contracts | `references/plugin-gates-and-fix-rounds.md` |

### Test quality
| Case | File |
|---|---|
| Property tests for isolation / scope / role surfaces; inert tests; exempt paths | `references/security-property-tests.md` |
| In-process scope property tests | `references/scope-test-in-process-execution.md` |
| Feature has tests but no production caller | `references/production-reachability-review.md` |
| Tests to update when the architecture shifts mid-loop | `references/architecture-refactor-test-updates.md` |
| Upgrade-path tests | `references/upgrade-path-test-pattern.md` |
| Before/after evidence pairs for delivery | `references/evidence-pairs.md` |

### Data and storage
| Case | File |
|---|---|
| Invariants, foreign keys, idempotency, money as TEXT/Decimal, migration fixtures | `references/data-integrity-principles.md` |
| SQLite table-rebuild migrations | `references/sqlite-migration-pitfalls.md` |
| SQLite WAL migration review findings | `references/sqlite-wal-review-findings.md` |
| Replacing N modules with one (caller inventory) | `references/full-module-replacement-scoping.md` |
| Reconciliation logic | `references/reconciliation-review-findings.md` |

### Surfaces and domains
| Case | File |
|---|---|
| REST API: routers, authz, SQL patterns | `references/rest-api-review-checklist.md` |
| MCP tool surfaces and design review | `references/mcp-category-tool-implementation.md`, `references/mcp-design-review-patterns.md` |
| App ↔ external source-of-truth sync (Sheets, SaaS mirrors) | `references/sync-pipeline-review-patterns.md` |
| Android APK / WebView verification | `references/mobile-app-verification.md` |
| Fill-template document extraction | `references/extraction-from-filled-docs.md` |
| Styling against a shipped minified bundle | `references/minified-bundle-selector-research.md` |

### Mechanics and process history
| Case | File |
|---|---|
| CLI flags, git mechanics, contract-test mechanics, push hygiene | `references/tool-mechanics-pitfalls.md` |
| Dispatch, polling, parallel builds, brief races | `references/pitfalls-dispatch-semantics.md` |
| CI and repo hygiene | `references/ci-and-repo-hygiene.md` |
| Batching a phase by dependency and risk | `references/multi-batch-sequencing.md` |
| Release-hardening-shaped cycle | `references/beta-gate-release-hardening.md` |
| Integrating an operator's field briefing | `references/field-briefing-integration.md` |
| Port notes: delegate-skills, planning-with-files | `references/delegate-skills-adaptation.md`, `references/planning-with-files-adaptation.md` |

## Adding a lesson

Add a lesson only when a loop taught something a future loop would get wrong
without it. One file per case; put the date and project type in the title;
add a row above. If the lesson changes how the loop runs (a cap, a stop rule,
who reviews), change `confirm-round-protocol.md` instead — a rule filed as a
lesson becomes a second, contradicting copy.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 323kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 323kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 323kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall