moonlight-lupin/agent-skills / plugins/dev-pipeline/skills/review-lessons
review-lessons
VerifiedLibrary 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.
references/pitfalls-dispatch-semantics.md
View on GitHub# Pitfalls — Dispatch Semantics
Reached from SKILL.md ## Pitfalls. Dispatching, polling, parallel builds, and model pins.
Re-read when a loop dispatches or monitors builders/reviewers. Split from SKILL.md
pitfalls in the 2026-10-16 refactor.
## Contents
- Do NOT tight-poll background builds
- Parallel Cursor builds for independent modules
- NEVER overlap a full-suite verification run with a builder dispatch on the same working tree
- Parallel Cursor dispatches on the SAME repo are safe only with disjoint file ownership declared in the briefs
- Model-name pins drift with CLI updates
1. **Do NOT tight-poll background builds — dispatch, then set a monitor timer** — when a Cursor build runs with `notify_on_complete=true`, do NOT loop `process(action="poll")` every few seconds. Each poll consumes one tool-iteration slot. A 5-8 min build burns 40+ polls, exhausting the iteration budget before the build finishes. User requirement (2026-09-15, wedding-rsvp session): when waiting for a coding agent, ALWAYS set a timer to monitor. Dispatch the build, then start a bounded background timer (`terminal(background=true, notify=true)` with `sleep <estimate>`; re-arm a fresh timer on each status report). Use each timer tick to poll ONCE and report progress — do not loop-poll between ticks. Do other useful work in between (write the next brief, prep tests). The completion notification arrives automatically. See `review-commit/references/background-build-polling.md` for the full pattern and cost analysis. Cursor-agent builds run LONG and QUIET: a multi-item brief can run ~2h before the first edit lands, with the CLI at ~1% CPU reading/reproducing; diff-stat growing then freezing signals the test/verify phase, not a hang — treat ~0% CPU with live sockets + open pipes as the model-response phase, and use `ps -o etime= -p <pid>` for true elapsed time (timer-firing count ≠ elapsed).
**Quiet mode ('just monitor'):** when the user says "just monitor" for an in-flight build/review, stop per-tick progress reports — each timer tick does its single poll silently; surface only on completion, a failed check, or a decision the user must make. Stale timers from superseded rounds get a one-line ignored treatment, not a report. Dual review (Codex + Muse concurrently, user directive for wedding-grade code) follows the same monitor-timer discipline. Ship-gate decision on residual findings: present the user a compact fix-vs-ship choice with your recommendation; on no response within the wait window, proceed with the recommended option (nothing touches production until deploy, so the choice is reversible) and say so. Confirmed 2026-09-15 wedding-rsvp: clarify timed out → recommended R6 dispatched.
2. **Parallel Cursor builds for independent modules** — when multiple modules each create their own directory with zero shared files (e.g. three new vertical modules), dispatch multiple Cursor CLI builds simultaneously instead of sequentially. Use the `session=` parameter on `terminal(background=true)` to give each build an isolated session so they don't clobber each other. Each build writes to a distinct module directory (`core_toolset/modules/<name>/`) and migration file (`migrations/NNN_<name>.sql`), so there are no merge conflicts. Verify each build independently (import check, test run, file existence) before committing. Commit in dependency order (leaf modules first, then modules that depend on them). This cuts wall-clock time from N×build_duration to ~1×build_duration for N independent modules. Validated Aug 2026 on a 3-vertical parallel dispatch.
3. **NEVER overlap a full-suite verification run with a builder dispatch on the same working tree** — a full suite takes ~9 minutes; a Cursor build edits files throughout. If you dispatch the next batch while the previous batch's verification suite is still running, the suite reads half-applied edits and produces FALSE failures (one deepening cycle: a period-close test failed under the overlap and passed 1-for-1 in isolation after the build finished). The failure shape is deceptive — it looks like a code regression and can trigger an unnecessary fix loop. Rule: one repo-mutating or repo-reading job at a time per working tree. Dispatch the next builder ONLY after the in-flight suite exits (`process(action="wait")` or the completion notification). During verification, write the NEXT brief and tests in /tmp (outside the tree) — that parallelism is safe; running suites against a tree under edit is not. Validated Aug 2026 on a Batch 3→4 transition.
4. **Parallel Cursor dispatches on the SAME repo are safe only with disjoint file ownership declared in the briefs** — pitfall #42's pattern (separate module directories) extends to same-repo mixes: code batch + docs-only batch + release-file batch can run simultaneously IF each brief states exactly which paths the builder may touch and forbids the others ("Do NOT touch any file under core_toolset/ or tests/" for docs briefs; "do not run or modify the red contract tests, another builder owns them" for mechanical briefs). Give each dispatch its own `session=`, log file, and brief path; commit in completion order after independent verification of each. Validated Aug 2026 on a Beta Gate (code batch via grok-4.6-high; docs + constraints batches via composer-2.5, all parallel, zero conflicts).
5. **Model-name pins drift with CLI updates — validate the model name at first dispatch, recover from the error's own list. The failure can be silent: under a `| tail -N` capture a stale model name exits 0 with empty output and no files written, indistinguishable from a successful quiet run — redirect full output to a log file, and after an exit-0 run that produced nothing, probe the model roster (the error text lists valid names) before blaming the builder** — an upstream CLI rename (e.g. `cursor-grok-4.7-*` dropped, `grok-4.7-*` added, `cursor-grok-4.6-*` retained) makes a pinned dispatch die in ~2 seconds with `Cannot use this model: X. Available models: ...`. Treat that error as the source of truth: pick the replacement from the error's available-models list (match generation + effort suffix, keep the user's canonical preference when it still exists) and re-dispatch immediately. Never re-dispatch with a guessed variant — a near-miss name can also fail in ways that waste a whole round. The 2-second fail-fast is the cheapest model-name check there is; no pre-flight list command needed.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |