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/sync-pipeline-review-patterns.md

View on GitHub
# Sync-pipeline review patterns (app ↔ external source of truth)

Depth for reviewing code that mirrors an external store (Google Sheets, an
exchange, a SaaS API) as the source of truth, with import / export / clear
operations. These five bug classes survived an initial build and one full
dual-review fix round before a confirmation pass caught them — reviewers
should probe for them explicitly, and briefs for sync features should
pre-empt them.

## Contents

- Locking
- Status-flag hygiene
- Idempotent append + reconcile
- Source-of-truth cell semantics
- Severity adjudication vs the live source of truth
- Deploy topology (tunnel + systemd + subdomain routing)
- Confirm-loop convergence signature (5-round case)
- PDPA / PII in check-in UIs
- Auth surface

## Locking

- **Fetch inside the lock.** Any fetch whose snapshot feeds a locked write
  must run inside the same lock. Fetch-before-lock reintroduces the race the
  lock exists to close: a destructive operation (clear) can commit between
  fetch and apply, and the stale snapshot then re-imports the cleared state.
  Sync operations are rare staff actions — holding the lock across
  fetch+apply is acceptable; a resurrected flag is not.
- **One writer lock across every mutating surface** — import, export, clear,
  and user mutations must serialize against each other, and read-only
  surfaces must either share the lock or fail fast (409 busy, retry) during a
  destructive window. Document that a threading.Lock is process-local; a
  multi-worker deployment needs a cross-process lock before this guarantee
  is real.

## Status-flag hygiene

- **Scope a bulk status-clear to the exact records processed in this run**
  (the snapshot IDs actually appended/written), never a blanket
  `UPDATE ... SET pending=0 WHERE pending=1`. Records that arrive between
  snapshot and update get their pending flag cleared without ever being
  processed — and are then stuck forever. Regression test: register a record
  mid-export; it must still carry the pending flag and export on the next
  run.
- **Destructive clears exclude retained history** (removed/flagged rows) in
  both the DB `WHERE` clause and the boundary computation for the external
  range. Compute the boundary from CURRENT live data, not retained history —
  a boundary derived from history can span rows the app no longer owns and
  wipe other parties' cells.

## Idempotent append + reconcile

- **Reconcile before append.** Before appending, search the external store
  for evidence the row already exists (stable marker text, then content
  identity such as name+category). An append that committed but whose
  response was lost must not produce a duplicate on retry — and an
  intervening import that created the same record under a different key must
  not become a second row. Reconcile must match by content identity as a
  fallback when the marker is missing.
- **Write any row marker AFTER field placements, or reserve its index.** A
  placement loop writing mapped fields into a dynamically-sized row will
  overwrite a marker written earlier into `row[0]` whenever a mapped field's
  resolved index is also 0 (e.g. the Name header sits in column A). Verified
  reproduction: marker written first, name placement last → marker replaced
  by the guest name. Write the marker last, or skip placements that collide
  with the marker index.
- **Skipping a placement is not discarding it.** The natural fix to the
  marker collision — `if index == marker_index: continue` — silently DROPS
  the displaced value (the guest name vanishes from the appended row).
  Verify both properties in the regression test: marker present AND every
  placement present. If index 0 is claimed by a placement, the marker must
  move (e.g. last column), not the placement disappear.
- **Reconcile that avoids a duplicate append but leaves two active records
  is incomplete.** When an import created the same party under a different
  key before export ran, clearing the orphan's pending flag leaves its
  future mutations never exporting (its key never matches the adopter) and
  both records visible to staff. Merge instead: adopt the record whose key
  matches the external store, carry the orphan's flags onto it (timestamp-
  newer wins), soft-delete the orphan (removed=1), preserve its audit
  trail. Test: two-phase fixture → exactly ONE active record after the
  next export, flags exported, audit events intact.
- **Close both sides of a merge/export window in the same round.** A merge
  that sets the adopter's pending flag is only half the fix when the merge
  runs AFTER the flag-export pass (flags land one cycle late) AND the
  import's blank-cell clear does not honor the pending flag (a stale
  snapshot in that window wipes the merged flag). Two cooperating gaps —
  ordering and clear-semantics — need both closed; fixing either alone
  fails the next confirmation round. Also verify import does not ingest the
  reconcile marker string as a field value (a `door:`/`gid…` marker parked
  in a name column gets upserted as the guest name); skip marker-shaped
  values before upsert.
- **Append rows built from the fetched header mapping**, never a fixed
  column layout — the external layout can reorder between runs.

## Source-of-truth cell semantics

- Decide and pin with tests: does a blank external cell mean "no data" or
  "clear the local value"? A `if not cell: return` early-return silently
  PRESERVES stale local state (a locally-set flag survives a blanked cell).
  For sheet-wins semantics, blank must clear. State the choice in the brief;
  a test must pin it either way.
- **"Value was inferred" flags are per-field, never per-record.** A single
  boolean covering N independent fields blanks all N in the UI when one is
  missing (adults blank + children=1 rendered as both unknown). Add one
  flag per field (additive columns with defaults; keep the old column for
  compatibility), set each independently, render `–` per-field.
- **Sheet-wins blanks meet pending exports.** The blank-cell clearing rule
  needs a pending-export exception: a locally-set flag whose export has not
  landed yet would be wiped by the next import's stale blank snapshot.
  Blank clears only rows WITHOUT a pending export (`AND needs_export = 0`
  in the clearing UPDATE); a non-blank sheet cell (staff ticked on the
  sheet) still wins over pending local state. Pair this with the
  merge-window rule above — they are two halves of the same race.

## Severity adjudication vs the live source of truth

Before accepting a reviewer's severity on a data-shape finding, read the
ACTUAL production data once (fetch the live header/rows). A real code defect
whose trigger case cannot occur with the live layout (e.g. the collision
requires a header position the production sheet never uses) is hardening,
not ship-blocking — classify it so, fix it for reorder-resilience, and say
so in the synthesis. The distinction matters both ways: a "cosmetic" finding
on a field staff tap hundreds of times on the day is not cosmetic.

## Deploy topology (tunnel + systemd + subdomain routing)

- **A running tunnel's ingress is extensible without new tunnels or
  credentials**: append a hostname entry to the local `config.yml`, restart
  the systemd unit, and add a proxied CNAME `<sub>.<zone>` →
  `<tunnel-id>.cfargotunnel.com` via the CF API (zone-scoped token with
  DNS + tunnel read works). Verify BOTH the new route and the existing
  route after the restart — a bad ingress edit takes the existing site
  down too.
- **Find which tunnel serves a domain empirically.** A `100::` AAAA on a
  proxied record means 'routed at the Cloudflare edge', not a normal
  origin — enumerate account tunnels + their configurations
  (`/cfd_tunnel/<id>/configurations`) before assuming; token-run tunnels
  (service binary with a JWT) decode via the `t` field of the base64
  token payload. A zone in the account does not mean the site's origin is
  in that account.
- **Remotely-managed tunnels show EMPTY local config** — a local
  `/etc/cloudflared/config.yml` may hold one tunnel's config while a
  different tunnel's rules live only in the CF API. Check both.
- **Systemd env-file + explicit venv python**: services need
  `EnvironmentFile=` (chmod 600) with every runtime secret and the exact
  venv interpreter path (`/usr/bin/python3` may lack the deps); a plain
  `python3` in ExecStart is the deploy-breaker. Verify with a full
  auth flow through the tunnel (no-auth 401, login, health, sync), not
  just a 200 on the index.

## Confirm-loop convergence signature (5-round case)

Diff-only confirmation rounds that name the prior findings explicitly
converge fast and predictably: full review (15 findings) → fix → confirm
finds 7 narrower residuals → 3 → 2 → 1 → SHIP. Two mechanics make it work:

- **Prompt the confirm round to also hunt for NEW bugs introduced by the
  fixes** — a pure verify prompt confirms fixes and stops hunting; the only
  rounds that found real regression-class bugs were the ones with a literal
  'check no new ordering bug was introduced' clause.
- **Reproduce every NOT-RESOLVED claim with an in-memory probe against the
  actual functions before writing the fix brief.** Reviewer claims are
  mostly real but scoped imprecisely; the probe gives the true severity and
  a failing case for the builder. One round's claim (merge flag loss) needed
  only a static trace to confirm; another (marker-as-name) needed a live
  probe. Probe both halves of a claimed two-mechanism bug — a claim can be
  real in one mechanism and wrong in the other.

## PDPA / PII in check-in UIs

Personal data from the source of truth may be REQUIRED in the DB (sync
columns) but forbidden in the UI. Separate the two: hide at render time
(`guest.mobile ? ... : ""` segments removed from the card template), keep
the DB/sheet path untouched, and say this split explicitly to the operator —
'hidden, not deleted' is a compliance claim they may need to defend. Same
pattern for any field that carries PII: mobile, ID numbers, full birthdate.
Apply this to intake forms too: if the UI must not SHOW mobile numbers,
the register form must not COLLECT them either — a hidden field still
creates a data liability (operator feedback on the deployed wedding
check-in: both the display and the intake field went).

Related UI-feedback pattern from the same operator round: terse toggle
labels are wanted but must stay decodable — replace word chips with
single-letter chips ONLY alongside `aria-label`s with the full word
("A" with `aria-label="Arrived"`), and never relabel a control in a way
that changes its API contract (the field name in the POST body stays
`arrived`/`gift` regardless of display). Category filters on a
mobile-first list UI want a `<select>`, not horizontally scrollable
pills — but a select that can hold an empty/"all" value needs an explicit
default: a fresh session with an empty value renders an empty list (see
pitfall #43 in SKILL.md) — default to the first real category on first
visit.

Post-launch operator feedback rounds on a staff UI (pattern from the
wedding check-in's post-deploy rounds):
- **"All" filters must fetch everything, and a first-visit default can
  mask the bug.** If the loader early-returns an empty list for the
  "all" value, verify by explicitly selecting it — the default-selected
  category hides the defect from casual checks.
- **Filter-side categories must come from the source's own catalog,
  not from guest rows** — a category defined in the source tab with zero
  tagged records must still appear; if the catalog persists only on
  sync-in, trigger one sync to populate it after deploying the fix.
- **RSVP-excluded guests must be filtered in the backend**, so footer
  and dashboard denominators stay consistent with the visible list (M
  parties = invited-excluding-No).
- **Role-split trays: the user may reject new auth in favor of
  ordering.** When two user roles share one login and destructive
  actions already sit behind a second password, put the staff-only
  action first and let the gate do the security — do not build an auth
  split nobody asked for.
- **Toggle chips read best light-until-active** — cream fill + thin
  gold border at rest, dark fill only when toggled on. A state-color
  treatment the operator calls "weird" reverts to this pattern.
- **Small visual deltas (name size, monogram text) are same-session
  one-line CSS/HTML fixes** — patch, bump the cache-bust query, restart,
  grep the served asset for the new value. Do not dispatch a builder for
  a token change; do say so explicitly per the delegation contract.

## Auth surface

- **Whitelist public static assets instead of blacklisting the sensitive
  file.** An exact-path deny (`path != "/static/index.html"`) is bypassed by
  duplicate slashes, trailing slashes, and dot segments
  (`/static//index.html/`, `/static/index.html/`) — normalization is fragile;
  a whitelist (`style.css`, `app.js` are public; everything else 401) is not.
  Test the bypass shapes explicitly.
- **Tokens never travel in URLs.** GET query tokens land in access logs and
  browser history. Login = POST body + HttpOnly cookie; legacy `?token=` URLs
  redirect to the login page, they do not authenticate.
- **Remove superseded routes entirely; do not leave a legacy alias behind.**
  A forgotten alias that skips the newer password/role gate is a bypass that
  every later review must rediscover.
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