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/reconciliation-review-findings.md

View on GitHub
# Phase 5.20 Reconciliation Review Findings

Learned from a reconciliation build phase (Aug 2026). Codex review caught 1 BLOCKING + 4 MAJOR issues in the reconciliation enhancement.

## BLOCKING: Multi-Invoice Suggestions Not Executable

Multi-invoice proposals stored `match_document_id = first_invoice_id` with `match_amount = combined_total`. `create_match` accepts only one document ID, and `confirm_match` applies the entire amount to that single invoice — normally failing because it exceeds the invoice's amount due.

**Fix:** Set `match_document_id = None` for multi-invoice proposals. They are suggestion-only — the user must create individual matches per invoice via `create_match`. The proposal includes `match_document_ids` (list) and `match_documents` (detail) so the user knows which invoices to match individually.

## MAJOR 1: Multi-Invoice Cross-Party Combinations

Combinations were built across ALL open invoices without grouping by `counter_party_id`. This could suggest combining unrelated customers' invoices and label the result with only the first customer's name.

**Fix:** Group invoices by `counter_party_id` before running combinations. Only combine invoices from the same party.

## MAJOR 2: Bank Balance Discards Opening Balance

`reconciliation_summary` summed transactions when history existed, discarding `se_accounts.balance`. This assumed a zero opening balance — an account with 1,000 balance and one 100 transaction reported 100 instead of 1,100.

**Fix:** Roll backward from the known current balance: `as_of_balance = current_balance - sum(transactions after as_of_date)`. This uses the imported current balance as the anchor point.

## MAJOR 3: Incompatible Count Units

`outstanding_count` counted bank entries (from `_bank_entries`) while `reconciled_count` counted match rows (`COUNT(*)`). Multiple confirmed matches on one entry made the counts incomparable.

**Fix:** `reconciled_count` uses `COUNT(DISTINCT rm.bank_entry_id)` — both counts now count bank entries.

## MAJOR 4: NULL Counter-Party GL Lines Omitted

`_gl_control_by_party` filtered `AND jl.counter_party_id IS NOT NULL`, omitting posted AR/AP control lines with no counter party. The tie-out could report "matched" despite an unallocated control-account balance.

**Fix:** `COALESCE(jl.counter_party_id, 0)` groups NULL lines under key 0. The reconciliation surfaces them as mismatches with `counter_party_name = "UNALLOCATED (NULL counter party)"`.

## General Patterns

- **Suggestion-only proposals:** when the execution path (create_match) only supports single documents, multi-document proposals must set the executable ID to None. The user sees the suggestion but cannot accidentally execute it.
- **Roll-backward balance calculation:** for as-of balance queries, anchor to the known current balance and subtract post-date transactions. Do not assume zero opening balance.
- **Count units must match:** when comparing counts in a summary, both counts must use the same unit (bank entries, not one entries and one match rows).
- **COALESCE for NULL foreign keys:** when grouping by a nullable FK, COALESCE to a sentinel (0) and label it clearly. Do not silently filter NULLs.
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