# Dispatcher Skill > Expert skilltree layer-1 dispatcher. Receives porting task commands from tasks.md, parses arguments, loads porting_item data and spec descriptions, then routes to the appropriate leaf skill for actual migration execution. Invoked as: /dispatcher-skill --specs --source or /dispatcher-skill --mode llm-freeform --source . Does NOT contain migration logic itself — only routing and data assembly. - Skill: `qualcomm/dispatcher-skill` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add qualcomm/dispatcher-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/qualcomm/dispatcher-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: qualcomm (https://skillmd.com/u/qualcomm) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/qualcomm/dispatcher-skill --- # Dispatcher Skill: Expert Skilltree Layer-1 ## Overview This skill is the routing layer of the expert skilltree. It receives porting commands from tasks.md, loads the relevant data, and dispatches to the correct leaf skill for execution. ``` tasks.md command → Dispatcher (parse + load + route) → Leaf Skill (execute migration) ``` --- ## 1. Argument Parsing ### 1.1 Invocation format > **Harness compatibility.** The `/dispatcher-skill …` forms below are the Claude > Code slash-command shorthand. This skill is harness-agnostic: on **Codex** (and > any harness without slash-command skills) there is no `/command` — invoke it by > describing the task in natural language while passing the same arguments > verbatim, e.g. *"Use the dispatcher-skill on porting item `` with specs > ``, source ``."* When `tasks.md` (generated by > easywos-spec) contains `/dispatcher-skill …` lines, treat each line as an > instruction to run the dispatcher with exactly those arguments. Only the surface > syntax differs; the argument parsing (§1.2) and routing (§2+) are identical > across harnesses. **Standard (with matched specs):** ``` /dispatcher-skill --specs --source ``` **No match (freeform):** ``` /dispatcher-skill --mode llm-freeform --source ``` **Retry after a failed attempt (loop re-entry):** ``` /dispatcher-skill --specs --source --feedback ``` ### 1.2 Parameter extraction | Parameter | Required | Description | |-----------|----------|-------------| | `` | Yes | ID of the porting_item to process (first positional arg) | | `--specs ` | One of specs/mode | Comma-separated global spec IDs from combined collection | | `--mode llm-freeform` | One of specs/mode | Freeform mode (no spec matched) | | `--source ` | Yes | Path to the matched YAML file | | `--feedback ` | No | Path to a feedback file from a prior failed attempt at this item. Present only on loop re-entry (attempt ≥ 2). When present, the dispatcher loads it into `prior_attempt_feedback` (§2.7) and passes it to the leaf skill so the retry corrects the specific prior failure instead of re-emitting the same output. | ### 1.3 Validation rules 1. `porting_item_id` MUST be present (first argument) 2. `--source` MUST be present 3. Exactly ONE of `--specs` or `--mode` MUST be present (mutually exclusive) 4. If `--specs` is present, value must be non-empty comma-separated integers 5. `--feedback ` is OPTIONAL; if present, the file MUST exist and parse (see §2.7). A missing/unreadable feedback file is a hard error — do NOT silently proceed as a first attempt, because that would drop the failure signal and let the loop re-emit the same broken output. 6. If validation fails, report error and stop --- ## 2. Data Loading & Assembly ### 2.1 Load porting_item from matched YAML 1. Read the file at `--source` path 2. Find the porting_item whose `id` matches `` 3. Extract: `context`, `semantics`, `constraints`, `register_mapping`, `code_range`, `match_confidence` 4. If not found → report error: "porting_item '' not found in " ### 2.2 Resolve spec routing via combined collection For each spec_id in `--specs`: 1. Read `skills/combined-spec-summary.yaml` 2. Find the spec entry with matching global `id` 3. Extract three routing fields: - `source` → leaf skill directory name (e.g., `"intrinsics-x64-to-arm64"`) - `source_sub_dimension` → file pair basename (e.g., `"arm64-limitations"`) - `source_id` → local spec id within that file ### 2.3 Load spec description from leaf skill yaml For each resolved spec: 1. Locate: `skills//references/specs/.yaml` 2. Find the spec entry with `id` == `source_id` 3. Extract: `name`, `description`, `x64_constructs`, `arm64_constructs`, `pitfalls`, `validation_criteria` ### 2.4 Load porting logic from leaf skill md For each resolved spec: 1. Locate: `skills//references/specs/.md` 2. Find the markdown section corresponding to the spec name 3. Extract the full section content as `porting_logic` ### 2.5 Assemble data contract Combine all loaded data into the standardized contract: ```yaml porting_item: id: context: semantics: constraints: register_mapping: code_range: matched_specs: - id: name: source: source_sub_dimension: source_id: description: porting_logic: match_confidence: rules_hit: scope_verified: llm_confidence: # Present ONLY on a retry (--feedback given); omitted on the first attempt. prior_attempt_feedback: ``` ### 2.6 Freeform mode data contract When `--mode llm-freeform`: ```yaml porting_item: id: context: semantics: constraints: register_mapping: code_range: matched_specs: [] directive: Load arm64-baseline-porting skill as constraint framework # Present ONLY on a retry (--feedback given); omitted on the first attempt. prior_attempt_feedback: ``` --- ## 2.7 Prior-Attempt Feedback (loop re-entry) The dispatcher is the re-entry point of the per-item porting loop: ``` dispatch → leaf skill emits ARM64 → build + gtest → PASS ✔ (item done) → FAIL ✘ → write feedback file → re-dispatch with --feedback ↺ ``` On a first attempt there is no `--feedback`, and `prior_attempt_feedback` is omitted from the data contract entirely. On any retry the orchestrator passes `--feedback `; the dispatcher loads that file and places it in the data contract so the leaf skill corrects **the specific prior failure** instead of regenerating the same output. ### 2.7.1 Feedback file schema The feedback file is YAML written by the verification stage after a failed build or test. The dispatcher does not author it — it only loads and forwards it. Expected shape: ```yaml attempt: 2 # 1-based; this is the attempt about to run prior_attempts: - attempt: 1 stage: build | test # where it failed failure_kind: compile_error | link_error | assertion | crash | timeout detail: | # verbatim, truncated compiler/gtest output test_pixel_sad.cpp:41: Failure Expected equality of these values: ref_sad -> 1184 arm64_sad -> 1152 failing_fixtures: [SadTest.Block16x16] # gtest names, if stage == test hypothesis: | # optional: verifier's guess at root cause Horizontal reduction likely used vaddvq over the wrong lane width, dropping the high 64 bits of the accumulator. ``` ### 2.7.2 How the leaf skill must use it The dispatcher passes `prior_attempt_feedback` through verbatim and instructs the routed leaf skill to, BEFORE emitting new code: 1. Treat every `failing_fixtures` / `detail` entry as a hard constraint the new output MUST satisfy — do not reproduce the same construct that failed. 2. Prefer addressing the `hypothesis` root cause over cosmetic edits. 3. If the same `failure_kind` has now recurred across attempts (visible in `prior_attempts`), change *approach* (e.g. different NEON reduction, or fall back per §3.5) rather than retrying the same fix — a repeated identical failure means the current strategy is exhausted. ### 2.7.3 Retry budget and terminal handling The orchestrator owns the retry counter, not the dispatcher. The dispatcher executes whatever attempt it is handed. But it MUST surface the attempt number in its output so a stuck loop is visible: ``` [ATTEMPT 2/K] — retrying after test failure (SadTest.Block16x16) ``` When the orchestrator's retry budget K is exhausted, it stops calling the dispatcher for that item and marks it `[NEEDS REVIEW]` (see §5.4) — the loop must have a terminal exit so one hard item never blocks the batch. --- ## 3. Routing Logic ### 3.1 Route via source field `source` → leaf skill directory: `skills//` ### 3.2 Route via source_sub_dimension `source_sub_dimension` → file pair: - `skills//references/specs/.yaml` - `skills//references/specs/.md` ### 3.3 Freeform mode routing When `--mode llm-freeform`: - Load `skills/arm64-baseline-porting/SKILL.md` - Apply all baseline constraints (16-byte alignment, flag discipline, etc.) - Execute migration using LLM's own knowledge within those constraints ### 3.4 Inline-asm handling (spec-routed, with detection fallback) ARM64 inline-asm kernels are matched through the NORMAL spec pipeline: `arm64-inlineasm-to-intrinsics` publishes specs (`references/specs/inline-asm-neon.yaml`) whose match_rules fire on `__asm__ __volatile__` blocks and quoted AArch64 NEON mnemonics (matcher scope `inline_asm`). When those specs match, they resolve via `source` to this leaf skill through the same routing as any other spec (§3.1–3.2, §4). **Spec-based routing is PRIMARY.** Detection fallback (safety net, subordinate to spec routing): if `porting_item.context` contains `__asm` or `__asm__` but NO spec resolved to `arm64-inlineasm-to-intrinsics` (e.g. the matcher missed it, or the item came through `--mode llm-freeform`), route to `skills/arm64-inlineasm-to-intrinsics/` anyway and pass any matched_specs as supplementary context. This fallback only engages when spec routing did not already select the inline-asm skill; it never overrides a spec-selected primary from §4.2. ### 3.5 Leaf skill not found fallback If the resolved `source` leaf skill directory does not exist: - Log warning: "Leaf skill '' not found, falling back to baseline" - Execute as freeform mode with `arm64-baseline-porting` constraints - Pass the spec `description` and `porting_logic` as supplementary guidance --- ## 4. Multi-Spec Combination ### 4.1 Same source — merge When multiple spec_ids resolve to the same `source` (same leaf skill): - Combine all porting_logic sections into `matched_specs` array - Route to that single leaf skill with all specs as context ### 4.2 Cross-source — primary selection When spec_ids resolve to different `source` values: 1. Group specs by `source` 2. Select primary: the source group with highest total `rules_hit` (from match_confidence) 3. Route to primary leaf skill 4. Include non-primary specs in `matched_specs` as supplementary guidance (marked as `supplementary: true`) --- ## 5. Confidence & Output ### 5.1 Normal output After leaf skill executes, output the ARM64 code directly. ### 5.2 Low confidence handling If `match_confidence.llm_confidence` == `"low"`: - Execute routing and migration normally - Append to output: `\n\n[NEEDS REVIEW] — Low confidence match. Human verification recommended.` ### 5.3 Error handling | Error | Action | |-------|--------| | porting_item not found in source YAML | Report error, stop | | Spec ID not found in combined collection | Report error, stop | | Leaf skill directory missing | Fallback to baseline (Section 3.5) | | spec.yaml file missing in leaf skill | Fallback to baseline, log warning | | spec.md section not found | Use yaml description only, log warning | | `--feedback` given but file missing/unparseable | Hard error, stop (§1.3 rule 5) — never proceed as a first attempt | ### 5.4 Retry exhaustion (terminal loop exit) When the orchestrator has spent its retry budget K on an item and calls the dispatcher no further, that item is marked `[NEEDS REVIEW]` with the last feedback attached, and the batch continues with the next item. The per-item loop MUST always terminate — either PASS (gtest green) or exhausted → review. An item that neither passes nor exhausts is a hung loop and is a bug in the orchestrator, not a valid state. --- ## 6. Spec Collection Management The combined spec collection at `skills/combined-spec-summary.yaml` is generated by: ```bash node skills/dispatcher-skill/scripts/combine-specs.js ``` **MUST be re-run when:** - A new leaf skill is created (with new `references/specs/*.yaml` files) - Any existing leaf skill's `*.yaml` file is modified - After running `leaf-skill-creator` in either create or add-yaml mode The script scans `skills/*/references/specs/*.yaml` and aggregates all specs with globally unique IDs, preserving `source`, `source_sub_dimension`, and `source_id`.