---
name: cortex-analyze
description: Read-only diagnosis of a Ninjo agent's performance via the cortex-gateway MCP — pull metrics, operational insights, and sampled conversations, score against the quality rubric, and output prioritized findings + suggested fixes (does NOT deploy). Use when the user wants to analyze, evaluate, audit, review performance, or understand how an agent is doing.
---

# cortex-analyze — diagnose performance (read-only, MCP-first)

Evaluate a deployed agent and produce a prioritized findings report. **This skill never deploys** —
hand fixes to `/cortex-iterate`.

## 1. Load context
- **Multi-influencer token?** If `get_me` returns `scope: "multi-influencer"`, the connection is **unscoped** — pass `influencer_id` (the **Influencer ID** from `meta.md`; resolve a user's "@handle" via `get_me`'s `influencers` map) on **every** cortex-gateway call. Single-influencer tokens ignore it. See `knowledge/mcp-tool-reference.md` › Ground rules › **Influencer scope**.
- `agents/<name>/meta.md` (agent_id, influencer_id, template) and `changelog.md` (recent fixes — so
  you can tell if a known issue regressed).
- `templates/principles.md` + the agent's motion flavor (`templates/principles-<flavor>.md` from
  `meta.md` — its target metrics are the bar to score against), `knowledge/best-practices-top10.md`,
  `knowledge/agent-metrics.md`, `templates/kpi-profiles.md` (the scoring rubric + metric definitions).

## 2. Pull the data (MCP only)
- `get_agent_metrics` — funnel, lead score, booking rate, happy-path / nurturing scores,
  monotonicity, relative-risk z-scores. (Tune `days`, `min_leads`.)
- `get_agent_insights` — 24h quick stats, hot leads awaiting follow-up, stalled-by-objection,
  funnel transition rates, content-source performance.
- `get_conversations` — quick sample by risk signal (curated mode). Always pull a mix:
  `bad`, `stuck`, `low-happy` (problems) **and** `high-happy`/`high-score`/`booking` (calibration).
- `search_conversations` — when you need precision instead of a preset: cross filters
  (e.g. `min_funnel: 4, has_booking_link: false`), a date window, or a specific
  `conversation_id`/`contact_username`. No implicit min-message floor — pass `min_messages: 3`
  to mimic `recent`. Paginated (`total_count`/`page`).

## 3. Score + diagnose
For each sampled conversation, score against `best-practices-top10.md` and note concrete violations
(BP-#). Cross-reference metric anomalies (e.g. high funnel + low lead score → premature CTA;
low nurturing score → shallow discovery). Group findings by severity (CRITICAL / HIGH / MED).

## 4. Report
Output, no deploys:
- **Headline**: 2-3 sentence health summary with the standout metrics.
- **Findings**: each = symptom → evidence (metric value + conversation quote) → likely root cause →
  suggested fix type (example / principle / data / trigger) — i.e. a ready brief for `/cortex-iterate`.
- **What's working**: keep the calibration positives so iteration doesn't regress them.
- Optionally append a dated summary to `agents/<name>/changelog.md` under an `### analysis` note.

## Modes (optional `$ARGUMENTS` flags)
- *(default)* QA — conversation-level quality review against the rubric.
- `--metrics` — metrics-first: lead with `get_agent_metrics` + peer comparison, lighter sampling.
- `--review` — exhaustive SDK audit: load the live `get_agent_config`, check template compliance,
  cross-file consistency (BP-5), and unguarded actions (BP-7) without needing conversations.

## When a tool fails or a capability is missing
Read-only skill, so retry freely. Follow `knowledge/self-sufficiency.md`: if `get_agent_metrics`/`get_agent_insights`
time out, retry, then fall back to a conversation-only QA and say which signal is missing. If you can't reach the
data needed for a root-cause (e.g. raw LLM traces aren't exposed via MCP), name the trace store an engineer should
check rather than guessing a cause.
