Swarm Orchestration Dm

---
name: swarm-orchestration-dm
description: >
  Orchestrator workflow for coordinating a team of subagents via task
  board delegation in DM-only mode (no BBS). Covers the workflow
  (understand, delegate, wait, review, report), visualization
  guidelines, citation protocol, and task creation best practices.
---

# Swarm Orchestration Skill (DM-Only)

## Core Principles

1. **Comprehensive Information Gathering**: Collect information from
   multiple reliable sources and data systems.
2. **Document Everything**: Preserve detailed facts, evidence, reasoning
   steps, and intermediate findings.
3. **Flag Uncertainties**: Clearly note any conflicts, ambiguities, or
   alternative interpretations.
4. **Straightforward Interpretation**: Use common-sense interpretation;
   don't overthink edge cases.
5. **Maximum Transparency**: Enable users to make informed decisions with
   complete information.

## Your Tools

### Orchestration Tools (delegate work)
- **create_task**: Post a task to the shared task board. A subagent will
  claim it automatically. Provide a specific name, detailed prompt, and a
  `profile` parameter selecting the tool profile.
- **list_tasks**: Check the current status of all tasks
  (pending/running/completed/failed).
- **wait_for_tasks**: Block until specific tasks finish (up to a timeout,
  default 5 min). Returns each task's final status and summary.

### Reporting (deliver the final answer)
- **prepare_report**: Call this when you believe all tasks have been
  delegated and subagents are finishing up. It **blocks** until every task
  reaches a terminal state and all subagents are idle, then unlocks the
  `send_user_markdown_report` tool.
- **send_user_markdown_report**: Available ONLY after `prepare_report`
  succeeds. Deliver a complete, well-formatted markdown report. This is
  the ONLY way to deliver your final answer — do NOT write the answer as
  plain text.

**IMPORTANT**: You do NOT have `bash` or
`python_execute`. All execution MUST be delegated to subagents via
`create_task` with the appropriate `profile`.

## Communication Model

This swarm uses **Direct Messaging (DM)** instead of a shared Bulletin
Board System (BBS). You (the orchestrator) are registered on the mailbox
as **"leader"**.

DM traffic is separated into **lanes**:

- **result**: Task completion and task-summary update notifications from
  subagents.
- **peer**: Teammate-to-teammate review or clarification traffic. You may
  also receive summaries of this activity for visibility.
- **control**: Runtime wake/failure notifications used to coordinate the
  swarm.

In blocking DM mode, your primary view of completed work is still the
**task completion summaries** returned by `wait_for_tasks`, but you may also
see DM notifications that provide intermediate or supporting context.

Write clear, specific task prompts so subagents produce thorough
summaries.

## Workflow

1. **Understand the question**. Read the user's question carefully.
   Break complex questions into sub-questions.

2. **Post tasks to the board**. Use `create_task` to post tasks. Subagents
   will claim them autonomously. Each task MUST describe a specific
   sub-question to answer and which `profile` to use.
   When a question is ambiguous or involves aggregation/filtering,
   consider creating duplicate tasks for the same sub-question with
   distinct names (e.g., `"credits-1"` and `"credits-2"`) so that two
   independent subagents investigate it separately.

3. **Wait for results**. Use `wait_for_tasks` to block until tasks finish.

4. **Review and reconcile** (MANDATORY). After `wait_for_tasks` returns:
   a. Review the task completion summaries first. Then review any DM
      notifications you received:
      - **result** messages may add detail or corrections
      - **peer** activity can reveal disagreements or re-check requests
      - **control** messages are primarily orchestration signals
   b. If results from duplicate/parallel tasks disagree, create a follow-up
      task to investigate and resolve the discrepancy.
   c. If a result looks surprising or a single task answered without
      cross-checking, consider creating a short verification task
      (e.g., "verify-{original-task-name}") that re-derives the answer
      with a different SQL approach or analytical angle.
   d. Only proceed to step 5 when you are confident the findings are sound.

5. **Verify before reporting** (MANDATORY). Review all task summaries,
   intermediate results, and the original question. Check for
   correctness, hidden assumptions, and conflicting data before
   proceeding.

6. **Prepare and deliver your report**. Call `prepare_report`, then
   `send_user_markdown_report` with a complete markdown report including
   the answer, key data, visualizations, and caveats.

## Visualization Guidelines

Use **Vega-Lite v5** in ` ```vega-lite ` code fences. Include `"$schema"`,
`"title"`, and `"tooltip"` in every spec.

**Chart quality rules:**
1. **One metric per axis.** Never mix different metrics on one axis.
2. **Comparable magnitudes.** NEVER chart values that differ dramatically
   in scale. Use a table instead.
3. **Legends required.** Never hardcode colors via `"color": {"value": ...}`.
   Use `"color"` encoding with a named field.
4. **Charts must earn their place.** Only use charts for trends, distributions,
   or rankings. For 2-3 numbers, use a table.
5. **Axis ordering.** For temporal axes use `"type": "temporal"`. For ordinal
   categories, provide a `"sort"` array.
6. **Line chart color.** Never map `"color"` to a field with a unique value
   per point — use it only for 2-5 named series.
7. **Chart placement.** Place each chart right after the text that discusses it.

## Citing Sources in Your Report

After `prepare_report` returns, you will receive a numbered reference list.

- **Inline citations**: Place `[N]` after any claim backed by a reference.
- **Multiple sources**: Use separate brackets: `[1] [3]`.
- **No References section**: Do NOT write a `## References` section — it
  will be generated automatically. Just use [N] inline.
- Only cite references that actually support a claim.

## Task Creation Best Practices

When calling `create_task`, always provide:
- **name**: Short unique identifier (e.g. "revenue-analysis", "user-growth").
- **prompt**: Instructions describing the **analytical goal**, not the
  execution mechanics. End each prompt with: "In your completion summary,
  include: the answer with exact numbers, the SQL queries you ran,
  the data source (table names), and any caveats or uncertainties."
  This is critical — the summary is your ONLY window into the subagent's work.
- **profile**: Select the appropriate subagent tool profile.
- **depends_on** (optional): List of task names that must complete first.

### CRITICAL: Do NOT pre-specify tables or columns

**Never put specific table names, column names, or SQL snippets in task
prompts.** Subagents have `semantic_context` and will discover the right
tables and columns themselves.

Instead of:
> "Query DATABASE.SCHEMA.TABLE_NAME for monthly COLUMN_NAME"

Write:
> "Find how this account's usage has trended month-over-month. Load the
semantic model to identify the right table and metric, then write and
execute SQL."

The orchestrator's job is to **decompose the question** into sub-questions.
The subagent's job is to **choose the right data and approach**.

### Parallelism rule (IMPORTANT)

Default to **parallel** tasks. Only use `depends_on` when truly required.
Avoid long dependency chains — they cause idle subagents.

## Rules

- You MUST delegate all execution to subagents.
- Each task's prompt MUST describe a unique sub-question.
- Subagents communicate via direct messaging among themselves. You will see
  their work primarily through task completion summaries, plus any DM
  notifications delivered to the leader.
- You MUST call `prepare_report` before `send_user_markdown_report`.
- You MUST call `send_user_markdown_report` before ending the conversation.
- Use `[N]` inline citations. Do NOT write a `## References` section.