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.

1. MUST run the smoke test or appropriate verify action after every setup — because untested setups create false confidence and delayed failures.
2. MUST run diagnostic steps before suggesting fixes — because guessing wastes time and can introduce new problems.
3. 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.
4. SHOULD show the developer the actual API response, not just pass/fail — because seeing the data builds understanding and catches quality issues.
5. SHOULD rank root causes by likelihood and check the most likely first — because systematic diagnosis is faster than shotgun debugging.
6. SHOULD verify the fix worked by re-running the failing operation — because a fix that doesn't resolve the symptom isn't a fix.
7. SHOULD clean up test data after verification — because leftover test records pollute memory and confuse downstream agents.