google-sync-debug
Skill227 starsChanged 50 days agoMITView on GitHub
Diagnoses Compass Google Calendar sync, OAuth, webhook, job, connection-health, and SSE failures by tracing the correct browser, backend, sync-service, provider, and storage boundary. Use when Google events are stale, imports or watches fail, reconnect is required, sync jobs stall, or connection health reports attention.
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- a11y-auditSkill
- chaosSkill
- qa-test-stagingSkill
- shipSkill
- simplifySkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 27
Do not guess across layers.
- Very specific: line 42
Never print credentials, refresh tokens, internal auth tokens, notification tokens, or the contents of compass.yaml.
- Very specific: line 63
Follow docs/development/local-development.md for incomplete setup.
- Distinctive: line 74
Check backend and sync liveness/readiness before debugging domain logic.
- Distinctive: line 82
Verify signed OAuth state, callback URL, scopes, and reconnect/revocation state.
- Very specific: line 96
Use correlation/job/resource identifiers where available, but redact provider payload content in reports.
- Distinctive: line 122
Use test adapters and drivers.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
When
Google events are stale, watches fail, reconnect is required, or SSE is quiet.
Steps
Classify symptom → local prerequisites → trace the boundary → narrowest test.
Output
The failing layer (browser, backend, sync, provider, storage) plus evidence.
Pass
A named boundary and a command or log that shows it.
Anti-patterns
Do not guess across layers. See
anti-patterns.md.
Escalate
OAuth grant, production data repair, or missing Google client secrets.
Debug Google sync
Find the failing boundary before changing code. Read:
docs/features/google-sync-and-sse-flow.mddocs/development/local-development.mddocs/development/testing-playbook.md#testing-realtime-and-sync-changes
Never print credentials, refresh tokens, internal auth tokens, notification
tokens, or the contents of compass.yaml.
1. Classify the symptom
Identify the first observable failure:
- OAuth cannot start or complete
- provider connection is missing, revoked, or requires reconnect
- initial import or repair does not finish
- Compass changes do not reach Google
- Google changes do not reach Compass
- backend changes arrive but the browser stays stale
- sync jobs remain pending, leased, or retrying
- health/readiness reports attention
Record user state, environment, effective service URLs, calendar/provider, and the last successful step without collecting sensitive payloads.
2. Verify local prerequisites
Follow docs/development/local-development.md for incomplete setup.
- Backend, sync service, MongoDB, and web must use the current worktree's effective ports.
- Google OAuth credentials and redirect URIs must match the selected port.
- Browser API and SSE traffic can remain local.
- Google watch notifications require a public HTTPS
sync.callbackBaseUrl(proxied as/sync/*). - A local HTTP backend can support OAuth and initial import but not inbound Google webhook delivery.
Check backend and sync liveness/readiness before debugging domain logic.
3. Trace the relevant path
Connection and OAuth
Trace web authorization → backend-facing connection API → sync internal auth → provider auth adapter → encrypted credential custody → connection metadata. Verify signed OAuth state, callback URL, scopes, and reconnect/revocation state.
Compass to Google
Trace the browser mutation → backend event command/integration boundary → sync command/job → provider writer → invalidation/change feed → backend SSE publish → web query invalidation.
Google to Compass
Trace provider webhook → notification verification → subscription/resource → pull job → provider reader → normalized event persistence → invalidation/change feed → backend SSE → web refetch.
Use correlation/job/resource identifiers where available, but redact provider payload content in reports.
4. Distinguish common failures
- OAuth redirect mismatch is not a webhook reachability failure.
- A successful optimistic UI update does not prove backend or provider persistence.
- A successful provider write does not prove invalidation/SSE delivery.
- A healthy SSE connection does not prove the sync job ran.
- Missing Google credentials can leave the sync service healthy but passive.
- Mongo readiness failure should be fixed before investigating provider calls.
- Revoked refresh tokens require reconnect behavior, not retry loops.
- Expired/missing subscriptions should flow through renewal/reconciliation.
5. Test the narrowest layer
- Provider-independent logic: focused
packages/syncunit test - Storage, leasing, custody, or job behavior:
*.db.test.tsthenbun run test:sync - Backend integration/SSE emitter: focused backend test then
bun run test:backend - Web listener/refetch state: focused web test then
bun run test:web - Shared payload/contract:
bun run test:core, affected consumers, andbun run type-check
Use test adapters and drivers. Do not call real Google APIs from automated tests or weaken notification verification to simplify a test.
Report
State:
- failing boundary and evidence
- last confirmed successful boundary
- root cause or remaining hypotheses, clearly separated
- safe fix and regression coverage
- commands/scenarios run
- setup limitation when live webhook or OAuth behavior could not be exercised
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

