agentleFS
SwitchbackTechSwitchbackTech/compass/.agents/skills/google-sync-debug/SKILL.md

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.

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
  1. Very specific:

    Do not guess across layers.

    line 27
  2. Very specific:

    Never print credentials, refresh tokens, internal auth tokens, notification tokens, or the contents of compass.yaml.

    line 42
  3. Very specific:

    Follow docs/development/local-development.md for incomplete setup.

    line 63
  4. Distinctive:

    Check backend and sync liveness/readiness before debugging domain logic.

    line 74
  5. Distinctive:

    Verify signed OAuth state, callback URL, scopes, and reconnect/revocation state.

    line 82
  6. Very specific:

    Use correlation/job/resource identifiers where available, but redact provider payload content in reports.

    line 96
  7. Distinctive:

    Use test adapters and drivers.

    line 122

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.md
  • docs/development/local-development.md
  • docs/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/sync unit test
  • Storage, leasing, custody, or job behavior: *.db.test.ts then bun 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, and bun 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:

  1. failing boundary and evidence
  2. last confirmed successful boundary
  3. root cause or remaining hypotheses, clearly separated
  4. safe fix and regression coverage
  5. commands/scenarios run
  6. setup limitation when live webhook or OAuth behavior could not be exercised

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.