Skill: Diagnostics

Verify setup and troubleshoot the Personize stack. Two modes:

• VERIFY — Proactive. Run after setting up memory, governance, pipelines, or workspaces to confirm they work.

• FIX — Reactive. Jump to the action that matches the symptom when something breaks.

When to Use This Skill

Verify mode:

• Just finished memorizing data and want to confirm it's stored and recallable

• Just set up guidelines and want to confirm agents can see them

• Just wired a pipeline and want to run one record end-to-end

• Just set up a shared workspace and want to confirm agents can read/write

• Want to run a periodic health check

Fix mode:

• Recall returns irrelevant, empty, or noisy results

• Memorized data isn't being extracted correctly

• Guidelines aren't reaching agents or return wrong content

• Getting 429 rate limit errors or partial batch syncs

• Trigger.dev or n8n workflows are failing

• Shared workspace is going stale or agents aren't contributing

When NOT to Use This Skill

• Need to store data → use entity-memory

• Need to create guidelines → use governance

• Need to build a pipeline → use code-pipelines or no-code-pipelines

• Need to understand the architecture → use solution-architect

Works With Both SDK and MCP

Interface How it works Best for

SDK (@personize/sdk ) Run verification scripts locally Developers, CI/CD

MCP (Model Context Protocol) Use memory_recall_pro , ai_smart_guidelines tools interactively Claude Desktop, ChatGPT, Cursor

Quick Smoke Test

If the developer isn't sure what's wrong or just wants to verify everything works, run this:

import { Personize } from '@personize/sdk'; const client = new Personize({ secretKey: process.env.PERSONIZE_SECRET_KEY! });

// 1. Auth — can we connect? try { const me = await client.me(); console.log(✅ Auth: ${me.data.organization.name} (${me.data.plan.name})); } catch (e) { console.log('❌ Auth failed:', e.message); console.log(' → Check PERSONIZE_SECRET_KEY'); }

// 2. Memory — can we store and retrieve? try { await client.memory.memorize({ email: 'diagnostics-test@example.com', content: 'Test record for diagnostics. This person works at Acme Corp as a VP of Engineering.', enhanced: true, }); const recall = await client.memory.recall({ query: 'Who works at Acme Corp?', email: 'diagnostics-test@example.com', }); console.log(✅ Memory: ${recall.data.memories.length > 0 ? 'stored and recallable' : '⚠️ stored but not yet recallable (indexing may take 1-2 min)'}); } catch (e) { console.log('❌ Memory failed:', e.message); if (e.message.includes('429')) console.log(' → Rate limited. See FIX: RATE-LIMITS.'); }

// 3. Governance — can we fetch guidelines? try { const guidelines = await client.ai.smartGuidelines({ message: 'test verification' }); console.log(✅ Governance: ${guidelines.data.compiledContext ? 'responding' : '⚠️ no guidelines set up yet'}); } catch (e) { console.log('❌ Guidelines failed:', e.message); }

// 4. Digest — can we compile context? try { const digest = await client.memory.smartDigest({ email: 'diagnostics-test@example.com', include_properties: true, include_memories: true, }); console.log(✅ Digest: ${digest.data.compiledContext ? 'compiling context' : '⚠️ empty'}); } catch (e) { console.log('❌ Digest failed:', e.message); }

MCP equivalent

1. Call memory_store_pro with content "Test record. Works at Acme Corp as VP Engineering." and email "diagnostics-test@example.com"
2. Call memory_recall_pro with query "Who works at Acme Corp?" and email "diagnostics-test@example.com"
3. Call ai_smart_guidelines with message "test verification"
4. Confirm each returns data

Based on results, jump to the appropriate VERIFY or FIX action below.

VERIFY Actions

Use after setting up a capability to prove it works.

Action When to Use Reference

VERIFY-MEMORY After memorizing data — confirm it's stored and recallable reference/verify-memory.md

VERIFY-GOVERNANCE After setting up guidelines — confirm agents can see them reference/verify-governance.md

VERIFY-PIPELINE After wiring a pipeline — run one record end-to-end reference/verify-pipeline.md

VERIFY-WORKSPACE After setting up a shared workspace — confirm agents can read/write reference/verify-workspace.md

HEALTH-CHECK Ongoing — diagnose quality, performance, and coverage issues reference/health-check.md

FIX Actions

Use when something is broken. Jump to the action that matches the symptom.

Action When to Use Reference

BAD-RECALL Recall returns irrelevant, empty, or noisy results reference/bad-recall.md

BAD-EXTRACTION Memorized data isn't being extracted correctly reference/bad-extraction.md

GOVERNANCE-MISS Guidelines aren't reaching agents or return wrong content reference/governance-miss.md

RATE-LIMITS Getting 429 errors or partial batch syncs reference/rate-limits.md

PIPELINE-FAILURE Trigger.dev/n8n workflows failing or producing bad output reference/pipeline-failure.md

WORKSPACE-STALE Agents not contributing or workspace going stale reference/workspace-stale.md

Constraints

Keywords follow RFC 2119: MUST = non-negotiable, SHOULD = strong default (override with stated reasoning), MAY = agent discretion.

• MUST run the smoke test or appropriate verify action after every setup — because untested setups create false confidence and delayed failures.

• MUST run diagnostic steps before suggesting fixes — because guessing wastes time and can introduce new problems.

• MUST use real queries that match the developer's actual use case, not generic test strings — because verification with irrelevant queries can pass while real queries fail.

• SHOULD show the developer the actual API response, not just pass/fail — because seeing the data builds understanding and catches quality issues.

• SHOULD rank root causes by likelihood and check the most likely first — because systematic diagnosis is faster than shotgun debugging.

• SHOULD verify the fix worked by re-running the failing operation — because a fix that doesn't resolve the symptom isn't a fix.

• SHOULD clean up test data after verification — because leftover test records pollute memory and confuse downstream agents.