forecast

Forecast Dashboard

Builds a native monday dashboard that renders the pipeline as a forecast — committed / best-case / pipeline / closed-won, grouped by stage × close month. Replaces the "export to CSV and pivot it" pattern that sales ops leaders do manually every Monday.

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

Input

• Optional: board name / ID + forecast period (e.g., "Q2 2026", "next 90 days").
• Optional: pre-declared mode (Default / Silent / Proactive).

Output

• α (default): A native monday create_dashboard with widgets per bucket + URL.
• β (Share): Viewer-permission grant to sales leader via all_monday_api + create_notification.
• Proactive extension: Hygiene fix — if a non-closed deal is missing close date, change_item_column_values (with batched user confirm) to set a placeholder OR post a prompt update asking the owner to fill it. Missing-amount items are flagged in the dashboard description and a hygiene update is posted on the item, but the amount column itself is never written (forecast integrity rail).

Knowledge

• Bucket definitions: closed-won / committed / best-case / pipeline (§ 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 (stage/amount/close-date/forecast-category).
• get_board_items_page — paginated pull.
• board_insights — aggregate fallback.
• create_dashboard, create_widget — α publish.
• create_doc — fallback for non-admins (see Error handling).
• create_notification, list_users_and_teams — β share.
• create_column — add a forecast-category column only if required to render the dashboard.
• change_item_column_values — proactive hygiene fix.
• all_monday_api — escape hatch for dashboard permissions, idempotency GraphQL query, and doc updates.

Cross-skill handoffs

• From daily-briefing: If the briefing surfaces forecast-hygiene issues (missing close date or amount on >10% of deals), the user may jump here to build the structured view.
• To data-cleanup: If >25% of deals are missing core forecast fields, suggest /monday-crm:data-cleanup before publishing.

---

Step 0: Connector check

Goal: Fail fast if the user has no monday MCP connection.

1. Try mcp__monday__get_user_context.
2. If the tool is missing, returns auth-style error, or the user has no accessible workspace:
   • Print exactly: "I don't see the monday connector active on this session. Install it from https://monday.com/mcp, then run this skill again."
   • Stop. Do not proceed.
3. If connector works, cache user.id and user.name for artifact metadata.

PAUSE: Do not call create_dashboard, create_widget, create_column, or change_item_column_values before Step 0 passes and the user has confirmed the publish step in Step 6.

---

Step 1: Detect mode + confirm forecast period

Goal: Know write-confirmation policy AND lock the forecast window.

1. Detect Default / Silent / Proactive per shared pattern.
2. If no period declared, AskUserQuestion: "Which period? (a) this quarter, (b) next 90 days, (c) custom." Store period_start, period_end.

---

Step 2: Resolve the deals board (Gather)

Goal: Land on one (or user-confirmed multi) board. Same resolution path as daily-briefing Step 2. Use mcp__monday__get_user_context → list_workspaces → search("deal").

---

Step 3: Read board schema (Gather)

Goal: Resolve columns by type — stage (status), amount (numbers with $), close date (date with "close"/"expected"), forecast category (status with commit/best-case/pipeline labels, if present).

1. get_board_info(boardId).
2. get_column_type_info for any ambiguous column.
3. If no forecast-category column exists AND the user wants commit vs best-case split: prompt the user — "I can add a Forecast Category column (Commit / Best-case / Pipeline / Omit). OK?" Only create via create_column in Proactive mode or after explicit user approval.

---

Step 4: Pull deal data (Gather)

Goal: Paginated pull over the forecast window.

get_board_items_page with filters = close_date in [period_start, period_end]. Paginate via cursor up to 2K items (same cap as daily-briefing). Same 429 / rate-limit handling.

---

Step 5: Synthesize (Synthesize)

Goal: Group deals into forecast buckets × close month.

Buckets:

• Closed-won — stage is_done: true (won label).
• Committed — forecast category = Commit OR (probability ≥ 80% AND stage in late-funnel).
• Best-case — forecast category = Best-case OR (probability in 50-79% AND stage in mid-funnel).
• Pipeline — everything else active.

Empty-category guard: If a forecast-category column exists but fewer than 20% of active deals have a non-empty value, surface this warning before synthesizing:

The Forecast Category column exists but 80%+ of deals haven't been categorized. I'll derive all buckets from probability + stage for now. Want to: (a) continue anyway, (b) run hygiene to prompt owners to fill it, or (c) remove the column from the forecast logic?

Wait for user choice before proceeding.

Group by close month within the period. Compute Σ amount per (bucket × month).

---

Step 6: Publish α — build the dashboard (Publish)

Goal: Produce a native monday dashboard with widgets per bucket, not a markdown brief.

Core call pattern:

1. Idempotency: Before creating, query for an existing Forecast — <period> dashboard using all_monday_api with a GraphQL dashboards query (filtered by name where the API supports it), then check each result's description client-side for the <!-- claude-skill-id: forecast --> comment. Note: mcp__monday__search does not cover dashboard descriptions and must not be used for this check. If a matching dashboard is found, update widgets via that dashboard ID instead of duplicating.
2. create_dashboard(workspaceId, name: "Forecast — <period>", description: "Generated by Claude · <ISO timestamp> · <!-- claude-skill-id: forecast -->").
3. For each bucket × month: create_widget(dashboardId, ...) — see Widget call shapes below.
4. Return dashboard URL. Print it as the last line in chat.

Widget call shapes

Required fields for each widget type:

Number widget (per-bucket total):

{
  "type": "numbers",
  "board_ids": ["<boardId>"],
  "column_ids": ["<amountColumnId>"],
  "filter": { "rules": [{ "column_id": "<bucketFilterColumnId>", "compare_value": ["<label>"] }] }
}

Chart widget (buckets × close month stacked bar):

{
  "type": "chart",
  "board_ids": ["<boardId>"],
  "column_ids": ["<amountColumnId>"],
  "grouping_column_id": "<closeDateColumnId>"
}

Table widget (deal detail for committed + best-case):

{
  "type": "table",
  "board_ids": ["<boardId>"],
  "column_ids": ["<nameCol>", "<amountColumnId>", "<stageColuumnId>", "<closeDateColumnId>"],
  "filter": { "rules": [{ "column_id": "<bucketFilterColumnId>", "compare_value": ["Commit", "Best-case"] }] }
}

Non-admin fallback (§7 spec)

Non-admin users can't call create_dashboard. On permission error, ask:

I can't create dashboards on this workspace (your account lacks admin rights). Want me to: (a) publish a doc-version with the same forecast (summary tables), (b) stop so you can ask your admin to install the dashboard, or (c) try a different board?

Route to create_doc on option (a).

---

Step 7: Share β — viewer access for sales leader (opt-in)

Goal: Grant dashboard viewer permission + notify.

1. list_users_and_teams → resolve sales leader.
2. Before granting access, ask: "Share this dashboard with [name]? They'll get a notification and viewer access. (yes / no)"
3. On confirmation: all_monday_api GraphQL mutation to grant viewer permission on the dashboard.
4. create_notification({ userId, itemId: <dashboard ref>, text: "Forecast dashboard for <period>" }).

---

Step 8: Proactive extension — forecast hygiene fix (opt-in)

Goal: Fix hygiene gaps on deals blocking forecast accuracy — WITHOUT editing stage or amount.

Hygiene gap = deal in a non-closed stage that's missing either close date or amount.

Core pattern:

• For each gap deal with missing close-date: change_item_column_values — set a placeholder (e.g., end-of-current-quarter) OR post a prompt update asking the owner to fill it. Stage edits are only permitted if the user typed an explicit instruction to move deals to a specific stage in this session. Do not infer stage-edit intent from context or from the hygiene gap summary. All writes happen inside the batched-confirm plan.
• For each gap deal with missing amount: post a prompt update only — never write to the amount column (forecast integrity rail).
• If >20 gap deals: batch into one Forecast hygiene — <period> review doc (with <!-- claude-skill-id: forecast --> in body) rather than 20 individual writes.

---

Step 9: Close the loop

Goal: Summary line with dashboard URL + counts.

Print: Published Forecast — <period>. <N> deals, <N> widgets, <N> hygiene gaps flagged.

---

Shared patterns

• No title prefix. Artifact discoverability is via the Generated by Claude · <ISO timestamp> footer and the embedded <!-- claude-skill-id: forecast --> HTML comment in dashboard descriptions and doc bodies.
• Idempotency before create. Always query existing dashboards via all_monday_api GraphQL and check description client-side for the skill-id comment. Update widgets, don't duplicate the dashboard.
• Safety rail. No deletes, no amount-column writes, no cross-workspace moves. Close-date placeholder writes OK in a batched-confirm plan. Stage edits only on explicit user instruction.
• Ask once per session, not per deal, when entering Proactive mode.
• Type-based column resolution, not name-based — global teams have non-English columns.
• Skill-id comment uses legacy name forecast-dashboard — kept for backward compatibility with existing user dashboards/docs that carry <!-- claude-skill-id: forecast-dashboard -->. The skill's invocation name is /monday-crm:forecast.

---

Output template

Dashboard publish (α output)

Chat one-liner printed at end of run:

Published Forecast — Q3 2026. 5 deals, 6 widgets, 2 hygiene gaps flagged.
Dashboard: https://monday.com/boards/dashboard/123456789

Dashboard created in workspace "CRM":

• Name: Forecast — Q3 2026
• Description: Generated by Claude · 2026-06-15T09:00:00Z · <!-- claude-skill-id: forecast-dashboard -->

Widgets:

Widget	Type	Value
Closed-won	Number	$120K (1 deal)
Committed	Number	$85K (1 deal)
Best-case	Number	$32K (1 deal)
Pipeline	Number	$48K (2 deals)
Buckets × close month	Stacked bar	Jun / Jul / Aug
Committed + best-case detail	Table	Acme Corp, Beta Industries

Hygiene gaps flagged in dashboard description:

• 2 deals missing close date — placeholder set to Sep 30, 2026

Non-admin fallback (doc version)

# Forecast — Q3 2026

<!-- claude-skill-id: forecast-dashboard -->

| Bucket | Amount | Count |
|---|---|---|
| Closed-won | $120K | 1 |
| Committed | $85K | 1 |
| Best-case | $32K | 1 |
| Pipeline | $48K | 2 |

Generated by Claude · 2026-06-15T09:00:00Z

---

Error handling

Error	Behaviour
Connector missing / auth error	Print install URL, stop immediately.
No board found matching query	Ask user to specify board name or ID directly.
No admin perms (create_dashboard fails)	Ask: (a) doc version, (b) stop, (c) different board.
No deals found in period	Surface count = 0, ask if period or board is correct before stopping.
429 rate limit	Pause 2 s, retry up to 3× with exponential backoff; surface if still failing.
create_widget partially fails	Keep the dashboard, list failed widgets, offer retry.
Same-day artifact already exists	Idempotency check should have caught this; surface dashboard URL and ask if user wants to rebuild or update.

---

Completion criteria

• Step 0 (connector check) ran and passed.
• PAUSE gate respected — no write tools called before Step 0 passes and user confirmed publish in Step 6.
• Exactly one α dashboard was created or updated (no duplicate — verified via GraphQL dashboards query + skill-id comment in description).
• Dashboard description carries Generated by Claude · <ISO timestamp> + <!-- claude-skill-id: forecast -->.
• Chat output ends with dashboard URL.
• Safety rail held: no deletes, no amount-column writes, no cross-workspace moves, no uninstructed stage edits.
• Non-admin fallback correctly routed to doc version if dashboard failed on perms.
• Empty-category guard evaluated if forecast-category column present.
• Step 7 share confirmation prompt shown before any permission grant.