board-diagnosis

Board Diagnosis

Structural audit of a CRM board — shaped as a CSM / admin deliverable. Surfaces missing-data patterns, stalled groups, column drift, automation gaps, and data-quality scores. Publishes a prioritized diagnosis doc in the user's workspace.

Flow: Trigger → Gather → Synthesize → Publish (α, default) → Share (β, opt-in) → Proactive extension (opt-in, fix tasks).

Input

• Optional: board name / ID via argument.
• Optional: pre-declared mode (Default / Silent / Proactive).

Output

• α (default): A create_doc diagnosis report in the user's workspace, title Board Diagnosis — <board name> — <Mon DD>. Body carries Generated by Claude · <ISO timestamp> + <!-- claude-skill-id: board-diagnosis --> for idempotency + auditability.
• β (Share): Share doc permission + create_notification to CSM.
• Proactive extension: create_item (fix-task) per issue, written into a Fix Tasks group with Source = Claude populated on a status column (auto-create the column with user confirm if missing); normalize trivial column data (phone, country code, email casing) via change_item_column_values; can also batch-edit owner / source / last-touch columns when the user confirms a plan. Never edits amount columns, never deletes.

Knowledge

• Diagnosis strands (§ Step 5).
• Shared artifact conventions (see Shared patterns section below).

Tools (MCP)

• get_user_context, list_workspaces, search — board resolution.
• get_board_info, get_column_type_info — schema + column types.
• get_board_items_page — sampled pull (up to 2K most-recent).
• board_insights — aggregate diagnostics.
• get_board_activity — stalled-group + last-activity detection.
• all_monday_api — probe automation rules (no wrapped tool exists for automation list).
• create_doc — α publish.
• create_item — proactive fix-task creation.
• change_item_column_values — only for trivial normalization (phone, country code).
• create_notification, list_users_and_teams — β share.

Cross-skill handoffs

• From morning-briefing: If briefing flags >30% unowned deals or structural hygiene issues, route here.
• From forecast-dashboard: If >25% of deals lack forecast-critical fields, route here before building the dashboard.
• To morning-briefing / forecast-dashboard: Once the user fixes the flagged issues, they can re-run those skills.

---

Step 0: Connector check

Goal: Same as morning-briefing Step 0. Fail fast on missing monday connector.

---

Step 1: Detect mode

Goal: Default / Silent / Proactive. Same pattern. Proactive here is higher-stakes (creates fix-tasks + can batch-edit columns) — the session-level confirm prompt should explicitly say:

Proactive mode will create fix-task items, normalize trivial column data (phone, country, email casing), and may batch-edit owner / source / last-touch columns where signal is clear. It will not edit amount columns, move items across workspaces, or delete anything. (a) Approve all, (b) Review each batch, (c) Deny all?

---

Step 2: Resolve the board (Gather)

Goal: Same resolution path as morning-briefing Step 2. get_user_context → list_workspaces → search("deal"). Allow "all" for multi-board audits (produces one doc per board).

---

Step 3: Read board schema (Gather)

Goal: Full column inventory + type classification for every column (not just CRM-critical ones — the audit looks at ALL columns to find drift).

1. get_board_info(boardId) → full column list.
2. get_column_type_info for any column where fill rate will be calculated.

---

Step 4: Pull data (Gather)

Goal: Enough data to compute fill-rate, staleness, and activity patterns. Paginate up to 2K most-recent items. Also pull:

• board_insights for aggregate stats.
• get_board_activity for the last 90 days.
• all_monday_api GraphQL query for board { automations { id, name, trigger, actions } } to probe automation rules.

Same rate-limit + error-handling as morning-briefing Step 5. On partial failures, continue — note which strand failed in the diagnosis doc.

---

Step 5: Synthesize — five diagnosis strands (Synthesize)

Goal: Produce a prioritized fix list across these strands:

1. Missing data patterns — required fields (stage, owner, value, close_date) blank on >25% of items. Compute fill-rate per column.
2. Stalled groups — groups with no item updates in >30 days (from get_board_activity).
3. Column drift — columns with data on <5% of items over last 90 days (likely abandoned). Suggest archive.
4. Automation gaps — stage-based automations absent on deal boards (from all_monday_api automation probe).
5. Data-quality score — % of items with complete core fields.

Rank findings by impact × fix-effort. P0 = data blocking forecast / reporting; P1 = hygiene; P2 = structural.

TODO: see spec §5.3 — exact scoring rubric, impact weights, and fix-task templates.

---

Step 6: Publish α — diagnosis doc (Publish)

Goal: create_doc in user's workspace with the full audit.

TODO: see spec §5.3 Publish (α). Core content sections:

• Score: overall data-quality score (0-100) + 5-strand breakdown.
• P0 fixes — concrete, actionable.
• P1 / P2 fixes — batched.
• Automation recommendations — per stage-based pattern missing.
• Column cleanup — archive list.

Idempotency: same-day title → update existing doc.

Non-admin fallback isn't applicable (docs don't require admin). But if Proactive mode is on AND user isn't admin, skip create_item fix-tasks with a note ("admin-only").

---

Step 7: Share β — route to CSM (opt-in)

Goal: Share doc + notify.

TODO: see spec §5.3 Share (β):

1. list_users_and_teams → user picks CSM.
2. Grant doc view/edit via all_monday_api.
3. create_notification to CSM with doc link.

---

Step 8: Proactive extension — create fix-tasks + normalize (opt-in)

Goal: Turn the diagnosis into action, but stay inside the safety rail.

For each P0 / P1 fix:

• create_item in a Fix Tasks group with title Fix: <issue>, assigned to board owner (or CSM if admin). Populate Source = Claude on the board's source/status column (auto-create the column with user confirm if missing).
• For trivial normalization (phone-number reformatting, country-code standardization, email lowercase): change_item_column_values. Never write to amount columns. Stage/owner/source/last-touch edits OK inside a batched-confirm plan, but call bulk-data-hygiene for board-wide passes — this skill stays focused on diagnosis-driven point fixes.
• If >20 fix-tasks: batch into one Fix Tasks — <date> doc list (with <!-- claude-skill-id: board-diagnosis --> in body) rather than creating 20 items.
• Never deletes columns, never archives groups, never removes automations.

TODO: see spec §5.3 Proactive extension — exact normalization rules (phone E.164, country ISO 3166, etc.).

---

Step 9: Close the loop

Goal: Summary line + doc URL.

Print: Published Board Diagnosis — <board> — <date>. Score <N>/100. <P0> P0 · <P1> P1 · <P2> P2. <N> fix-tasks created.

---

Shared patterns

• No title prefix. Artifact discoverability is via the Generated by Claude · <ISO timestamp> footer and the embedded <!-- claude-skill-id: board-diagnosis --> HTML comment in doc bodies. For items the plugin creates, use Source = Claude on a status column (auto-create the column with user confirm if missing).
• Idempotency before create. Always search for same-day artifact (by title + skill-id comment) first. Update, don't duplicate.
• Safety rail. No deletes, no amount-column writes, no cross-workspace moves. Stage/owner/last-touch/source edits OK in a batched-confirm plan.
• Ask once per session, not per item, when entering Proactive mode.
• Type-based column resolution, not name-based — global teams have non-English columns.

Error handling reference

Failure	Behavior
Connector not installed	Step 0 stops; print install link.
No CRM board	Step 2 stops; offer path to /monday-crm:workspace-builder.
Board >10K items	Cap at 2K most-recent, flag sampling.
MCP tool error (retryable)	Exponential backoff 3x; on third fail, skip that strand, surface partial report.
Same-day artifact exists	Update in place via doc ID.
429 rate limit	Backoff 3x, then stop with retry note.
Non-admin publish perms	Degrade to print-only.
Non-English column names	Resolve by type via get_column_type_info.

Additional:

• board_insights 9% baseline error → on retry failure, skip that strand; diagnosis still produced with hygiene-line noting the missing strand.
• Automation probe fails (all_monday_api auth scope) → skip strand 4 with note "couldn't inspect automations — ask admin to re-run".

---

Completion criteria

• Step 0 (connector check) passed.
• Exactly one α diagnosis doc created or updated per board (verified via skill-id comment).
• Doc body carries Generated by Claude · <ISO timestamp> + <!-- claude-skill-id: board-diagnosis -->.
• All five diagnosis strands ran or are explicitly skipped with reason.
• Items the skill created carry Source = Claude on a status column.
• Safety rail held: no deletes, no amount-column writes, no cross-workspace moves.
• Proactive record edits ran inside a batched-confirm plan (no per-item ad-hoc writes).