docs(db): record the execution traps and parallel-session coordination rules - #2027
Conversation
…ation rules The playbook is already the multi-session guide, so this extends it rather than adding a fourth overlapping document — CLAUDE.md's whole argument for keeping AGENTS.md, CLAUDE.md and codebase-index.md non-overlapping is what stops five AI systems drifting apart, and a separate coordination file would have duplicated the phase list, refs and status and gone stale the moment one was updated alone. What the playbook did not carry is the failure knowledge. Two additions: Traps this programme has already hit — all observed, none hypothetical: - the newest migration mentioning a match_* function often only re-asserts grants and contains no body at all (20260724130000, 20260724120000), while the functions are redefined 2-16 times each; - joining manifest signatures to live regprocedure text reports all 93 functions as simultaneously missing and extra, which is a join failure and not a finding; - ledger rows must be resolved by exact title AND confirmed still in the open table — the anchor was once cited as #312, an unrelated row, and a close for #333 matched the archived row and threw "#333 is already archived", which red-lined docs:check-links for a whole branch; - Node 24 is mandatory under engine-strict, and a container shipping Node 20/22 fails npm ci with EBADENGINE and leaves tsx unresolvable; - two tooling failures are already fixed in PR #1978, so their symptoms should be recognised rather than re-diagnosed. Running two phases at once: phases with different targets can run concurrently, but the collision surface is the ledger, not the database. One ledger row per session assigned explicitly in the prompt; one reconciliation at a time from a fresh base; never merge main into a PR carrying a reconciliation; and verify merged content on main rather than the commit title (#324). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BKNFogaYfCQBvFVqFQnfRt
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in:59 minutes Limit details: You’ve used all 1 included review currently available under your plan. You completed 95 included PR reviews in the past 7 days; at that activity level, included reviews refill at 1 review per hour. Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
Comment |
This pull request has been ignored for the connected project Preview Branches by Supabase. |
Summary
Makes durable the knowledge a long multi-session session accumulated but the repo did not hold: the traps this remediation programme has already hit, and the rules for running two phases concurrently.
This extends the playbook rather than adding a new coordination document, deliberately. A
docs/database-remediation-coordination.mdwas the obvious move and I decided against it: the playbook already opens with "This playbook exists so the work can be executed across many separate chat sessions" — it is the coordination guide. A fourth file would have duplicated its phase list, refs, status and prompts, and gone stale the moment one of the two was updated alone.CLAUDE.md's argument for keepingAGENTS.md/CLAUDE.md/codebase-index.mdnon-overlapping is precisely the drift this would have created.What the playbook genuinely lacked was the failure knowledge, so that is what this adds.
Traps this programme has already hit
All observed during execution; none hypothetical.
match_*function often does not define it. These functions are redefined 2–16 times each across migrations, and20260724130000_explicit_base_match_rpc_execute_grants.sql— the newest file mentioning several of them — contains zerocreate or replace function; it only re-asserts grants. Same shape for20260724120000_table_facts_plpgsql_execute.sql. Verified by inspection, and it matters directly for Phase 1.2: diffing against a grants-only file would produce a meaningless result.#312, an unrelated Playwright row. Separately, a close request for#333was queued after confirming a#333row existed — but the match was the archived row, and the invalid request threw#333 is already archived, red-liningdocs:check-linksfor the whole branch. The existence check was not the check that mattered.engine-strict; a container shipping Node 20/22 failsnpm ciwithEBADENGINEand leavestsxunresolvable, which failscheck:runtime.guard-pushbase resolution. Their symptoms are named so a future session recognises them instead of re-diagnosing, and knows neither should need an override.Running two phases at once
Phases with different targets — Phase 1.2 read-only against production, Phase 2 mutating staging — can safely run concurrently. The collision surface is the ledger, not the database:
maininto a PR carrying a reconciliation — it turns a complete transaction into a partial one.main, not the commit title (#324).Verification
npm run verify:pr-localnpm run docs:check-links→docs link check passed: 1767 repo path references resolve.npm run docs:check-index→ coverage OK.npm run formatrun and committed.Documentation-only scope, so the gate stayed on the focused docs route — no lint, typecheck, test or build, correctly.
Not run:
verify:ui, provider-backed gates — nothing here touches UI or a provider.RAG impact
Not required: documentation only. No file under
src/lib/rag/**, nomatch_*RPC, no ranking, selection, eval-harness or fixture surface. The RPCs are described, not changed.Risk and rollout
git revertthe single commit.Notes
Generated by Claude Code