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

references/architecture-refactor-test-updates.md

View on GitHub
# Architecture Refactor: Test Update Pattern

When a build-review-loop fix round changes the internal architecture (e.g.
routing compat functions through a new CAS path instead of the old full-table
rewrite), tests that patch the OLD internal mechanism will fail — and this is
correct behavior, not a regression.

## Pattern (validated Aug 2026, a SQLite state-store migration)

### The problem

Tests that validate the OLD architecture's internal mechanism:

```python
# OLD test — patches _save, expects retry behavior
with patch("state_db._save", side_effect=flaky_save):
    result = mark_executed(config, action["id"], {"success": True})
assert call_count["n"] >= 2  # must have retried
```

After the fix routes `mark_executed` through `transition_action()` (CAS),
`_save` is never called. `call_count` stays at 0. The test fails.

### The diagnosis

This is NOT a regression — the test validates an implementation detail that
was deliberately replaced. The test must be rewritten to validate the NEW
architecture's behavior:

```python
# NEW test — validates CAS behavior, not _save retry
result = mark_executed(config, action["id"], {"success": True})
assert result is not None
assert result["state"] == "executed"
```

### Decision matrix

| Test failure cause | Action |
|---|---|
| Test patches OLD internal function (`_save`, `_with_retry`) | Rewrite test to validate NEW mechanism |
| Test asserts OLD state machine path (e.g. retry count from `_save` calls) | Rewrite to assert NEW path (e.g. CAS rowcount, transition result) |
| Test asserts OLD error type (`ConcurrencyError` from version mismatch) | Update to assert NEW behavior (`None` return from CAS mismatch) |
| Test asserts OLD side effect (YAML mirror written by `save_store_atomic`) | Update to assert NEW side effect (SQLite row exists) |
| Test fails because a NEW behavior is correct (e.g. `StateCorruptionError` raised on corrupt JSON where before it was swallowed) | Update test to expect the raise (this is the fix working as intended) |

### Key principle

When the orchestrator changes architecture (routing through a new path,
deleting old machinery), the orchestrator is responsible for updating tests
that validated the old mechanism. These are NOT Cursor fixes — they are
Hermes fixes because:

1. The tests encode the OLD contract, which was deliberately changed
2. The new behavior is correct — the test is wrong
3. The fix is in test-only code (per pitfall #20 — safe for Hermes to fix directly)

### What NOT to do

- Do NOT revert the architecture change to make the test pass
- Do NOT add the old `_save` call back as a compatibility shim
- Do NOT skip the failing tests
- Do NOT mark the tests as `@pytest.mark.skip` with a TODO

### What TO do

1. Read the failing test
2. Identify what OLD mechanism it patches/asserts
3. Rewrite it to validate the NEW mechanism
4. Run the full suite to confirm no other tests broke
5. Commit with message explaining the test was updated for the new architecture
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated 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