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/ci-and-repo-hygiene.md

View on GitHub
# CI and Repository Hygiene Pitfalls

Learned from a sixth-pass review (Aug 2026). Three findings, all reproduced.

## R3: CI Only Runs on Master — Feature Branches Are Blind

### The Problem

The CI workflow only triggers on `push: branches: [master]`. All development happens on feature branches. Sixteen phases of work landed on a branch that CI never evaluated. Two shipped defects (migration 055 data loss, missing l10n file) would have been caught by the existing test suite if CI had run on the branch.

### The Fix

One line of YAML:

```yaml
on:
  push:
    branches: ['**']    # was: branches: [master]
  pull_request:
    branches: [master]
```

This runs CI on every push to every branch. The cost is negligible (a few minutes of CI per push). The benefit is that defects are caught at push time, not at merge time — and not in a customer's books.

### General Rule

CI should run on every branch where work happens. If development happens on feature branches, CI must trigger on `branches: ['**']`, not just `master`. A CI pipeline that only watches the merge target is a post-hoc validator, not a guardrail.

## R2: Unanchored .gitignore Rules Eat Source Assets

### The Problem

A `.gitignore` rule like `data/` (unanchored) matches any directory named `data` at any depth in the tree. The rule was intended to keep runtime entity databases (`data/` as the default runtime data directory) out of the repo. But it also swallowed `core_toolset/data/l10n_registry.json` — a source asset one directory up from the whitelisted path.

The negation `!core_toolset/modules/**/data/` only covered the modules path. The source asset at `core_toolset/data/` was never tracked.

### The Fix

Anchor the rule to the repo root, and add a matching negation:

```gitignore
/data/           # was: data/ (unanchored)
/data_*/
!core_toolset/modules/**/data/
!core_toolset/modules/**/data/**
!core_toolset/data/       # NEW: whitelist source assets
!core_toolset/data/**     # NEW: whitelist contents
```

### Detection

```bash
git ls-files core_toolset/data/    # empty → file not tracked
git log --all -- core_toolset/data/  # empty → never committed
```

If a test file fails with `FileNotFoundError` on a data file that exists locally but is missing on CI or fresh clone, check `.gitignore` first.

### General Rule

Always anchor `.gitignore` rules that are meant to exclude top-level runtime directories. Use `/data/` not `data/`. After adding any new source asset under a path that shares a name with an ignored directory, verify it's tracked with `git ls-files`. Sweep for other swallowed assets after fixing the rule.

## R1: Migration Data Loss — See sqlite-migration-pitfalls.md

The full migration 055 data-loss story is in `references/sqlite-migration-pitfalls.md`. The key lesson for CI: fresh-DB tests cannot catch upgrade-path data loss. Write upgrade-path tests that seed real data before migration and verify row counts after. See `references/upgrade-path-test-pattern.md`.

## Git/CI principles distilled from past projects (2026-10-16)

- **Anchor .gitignore patterns.** An unanchored directory pattern (e.g. a bare `data/`) swallows package data directories anywhere in the tree: the file exists locally, is never committed, and everything fails on a fresh clone. Anchor directory patterns to the intended level, add negations for package data, and verify with a clean-clone run.
- **CI must trigger on the branches where development happens.** A push trigger limited to the default branch means CI never runs on the feature branch where the work lands — both repo-hygiene and behavior bugs ship untested. Set the push trigger to all branches (or at least the development pattern in use); default-branch-only triggers are for release tags only.
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