dispatcher-skill

name	dispatcher-skill
description	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 <porting_item_id> --specs <ids> --source <path> or /dispatcher-skill <porting_item_id> --mode llm-freeform --source <path>. Does NOT contain migration logic itself — only routing and data assembly.
tags	["dispatcher","skilltree","routing","arm64","porting"]

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

Standard (with matched specs):

/dispatcher-skill <porting_item_id> --specs <comma-separated-spec-ids> --source <matched-yaml-path>

No match (freeform):

/dispatcher-skill <porting_item_id> --mode llm-freeform --source <matched-yaml-path>

Retry after a failed attempt (loop re-entry):

/dispatcher-skill <porting_item_id> --specs <ids> --source <matched-yaml-path> --feedback <feedback-path>

1.2 Parameter extraction

Parameter	Required	Description
<porting_item_id>	Yes	ID of the porting_item to process (first positional arg)
--specs <ids>	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 <path>	Yes	Path to the matched YAML file
--feedback <path>	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 <path> 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 <porting_item_id>
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/<source>/references/specs/<source_sub_dimension>.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/<source>/references/specs/<source_sub_dimension>.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:

porting_item:
  id: <porting_item_id>
  context: <source code from matched YAML>
  semantics: <description>
  constraints: <list>
  register_mapping: <mapping>
  code_range: <range>

matched_specs:
  - id: <global_spec_id>
    name: <spec_name>
    source: <leaf-skill-name>
    source_sub_dimension: <file-basename>
    source_id: <local-id>
    description: <spec description from yaml>
    porting_logic: <detailed migration guidance from md>

match_confidence:
  rules_hit: <count>
  scope_verified: <bool>
  llm_confidence: <level>

# Present ONLY on a retry (--feedback given); omitted on the first attempt.
prior_attempt_feedback: <see §2.7>

2.6 Freeform mode data contract

When --mode llm-freeform:

porting_item:
  id: <porting_item_id>
  context: <source code>
  semantics: <description>
  constraints: <list>
  register_mapping: <mapping>
  code_range: <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: <see §2.7>

---

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 <path>; 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:

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     

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] <porting_item_id> — 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/<source>/

3.2 Route via source_sub_dimension

source_sub_dimension → file pair:

• skills/<source>/references/specs/<source_sub_dimension>.yaml
• skills/<source>/references/specs/<source_sub_dimension>.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:

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.