Easywos Spec

EasyWoS-Spec: Spec Matching & Task Generation Skill

Overview

This skill orchestrates the pipeline:

EasyWoS YAML input → Script initial screening → LLM semantic refinement
→ Matched YAML output → tasks.md generation with dispatcher invocations → Unit test verification

0. Dependency Preflight Check (MUST run first)

Before doing any other work, this skill MUST verify that all dependent skills and data files it relies on are present. Do this as the very first action when the skill is invoked.

0.1 Required dependencies

0.2 Check procedure

1. For each row above, confirm the path exists.
2. Collect the names of all missing dependencies (do not stop at the first one).

0.3 If any dependency is missing - report first, install only with approval

If one or more dependencies are not found, do not proceed with parsing, screening, matching, or task generation. Instead:

1. Handle generated data separately. If the only missing dependency is skills/combined-spec-summary.yaml and dispatcher-skill is present, regenerate it with:

   node skills/dispatcher-skill/scripts/combine-specs.js
   

   Then re-run the 0.2 check.

2. For missing skill directories or scripts, stop and report first. Do not automatically install packages or run network-backed commands. List the complete missing set and ask the user whether to install from the canonical repo.

3. Only after explicit user approval, run:

   npx skills add qualcomm/EasyWoS/agent --all
   

4. Re-run the 0.2 check after installation completes.

5. If dependencies are STILL missing, stop and report the complete list of the dependencies that remain absent, then ask the user to locate or install them manually. For example:

   Cannot run easywos-spec: the following dependent skills/files were still not
   found:
     - skills/dispatcher-skill/SKILL.md
     - skills/sse-avx-to-neon/SKILL.md
   
   These are required to route porting tasks and generate the matched output.
   Approve `npx skills add qualcomm/EasyWoS/agent --all`, or locate/install
   these dependent skills manually, then re-invoke easywos-spec.
   

Only when all dependencies in 0.1 are present may the skill continue to Section 1.

Note: skills/combined-spec-summary.yaml is generated by node skills/dispatcher-skill/scripts/combine-specs.js; do not ask the user to reinstall skills just to recreate this generated file.

1. Input Parsing

1.1 Receive EasyWoS YAML file

Parameter: Path to EasyWoS-generated YAML file (provided as skill argument or referenced in the OpenSpec change context).

Harness compatibility. The /easywos-spec … form is the Claude Code slash-command shorthand. This skill is harness-agnostic: on Codex (and any harness without slash-command skills) there is no /command — trigger it by describing the task in natural language and giving the same YAML path, e.g. "Use the easywos-spec skill to match <path-to-easywos-output.yaml> to specs." The /dispatcher-skill … commands this skill emits into tasks.md (§5) are likewise the Claude shorthand; on Codex, treat each such line as an instruction to invoke the dispatcher-skill with those exact arguments. Only the surface syntax differs.

/easywos-spec <path-to-easywos-output.yaml>

1.2 Validate and extract porting_items

1. Read the YAML file
2. Verify schema: x64-to-arm64-porting is present at the top level
3. Extract the porting_items array
4. If porting_items is empty or missing, report "No porting items found" and stop
5. For each porting_item, resolve its source code context:
   • Read the file at file_path (relative to the YAML file's directory)
   • Extract lines specified by code_range (e.g., 21-30 means lines 21 through 30 inclusive)
   • Use the extracted content as the item's context for all subsequent pipeline stages

Whole-file assembly items. When a porting_item's code_range covers an entire hand-written assembly file (a large file containing many independent kernels/procedures rather than one logical unit), it must not be matched or dispatched as a single item. The screening script (§2) automatically decomposes such items into per-kernel group children before matching. See Section 1.4.

1.3 Load spec collection

Read the predefined spec collection file:

skills/combined-spec-summary.yaml

Extract all specs[].id, specs[].name, specs[].description, and specs[].metadata.match_rules for use in the matching phase.

1.4 Whole-File Assembly Decomposition (per-kernel grouping)

When a porting_item describes an entire assembly file, treating it as one unit breaks the pipeline in two ways:

1. Match saturation — a very large file trips nearly every spec's match_rules somewhere, so the candidate list loses all discriminating power and every item appears to match every spec.
2. Un-actionable tasks — a single task spanning thousands of lines (e.g. "port lines 1–N" of a whole file) cannot be handed to a leaf skill, and there is no granularity for per-kernel unit-test verification.

To handle this, the screening script performs a decomposition pre-pass.

1.4.1 Trigger policy

The 400-line threshold is the default for distinguishing a whole multi-kernel file from a single logical unit; pass --threshold N to the script to tune it for a given project.

1.4.2 How decomposition works

1. Split on structural boundaries. The file is scanned for kernel entry points: cglobal / cvisible (NASM x86inc dialect) or <name> PROC (MASM). Each entry begins a kernel that runs until the next entry.

2. Aggregate variants into groups. Size/CPU variants of the same logical kernel are merged by a normalized group key (kernelGroupKey). The normalization rules are:

   • Underscore-delimited ISA/CPU-feature suffixes (e.g. _sse2, _avx2, _neon, _mmx) are stripped — they denote the instruction set, not a different kernel.
   • Underscore-delimited dimension suffixes such as a WxH block size (e.g. _16x16, _8x8) are stripped, including macro-truncated fragments left by templated codegen (a trailing _NNx or a dangling _).
   • A trailing short batch/arity dimension such as _x3 / _x4 is retained — it marks a genuinely different algorithm variant, not a size.
   • When the dimension is fused into the name (no underscore separator, e.g. a trailing number glued to the base name), the name is kept as a distinct kernel rather than merged. Such names usually denote genuinely different routines, not size variants of one routine.

   Generic examples (using a base name foo): foo_16x16_sse2, foo_8x8_avx2 → group foo; foo_x4_16x16 → group foo_x4; foo8, foo16, foo32 (fused) → three separate kernels.

3. Emit one group child per group, in first-appearance order.

1.4.3 Group child shape (what the script outputs per group)

Each decomposed group appears in the script's JSON candidates as a normal entry, plus these extra fields:

{
  "porting_item_id": "<parent_id>__foo",
  "parent_id": "<parent_id>",
  "group": "foo",
  "code_range": "440-512, 980-1040, 1600-1672",
  "functions": ["foo_16x16_sse2", "foo_8x8_sse2", "..."],
  "function_count": 40,
  "matches": [ { "spec_id": 1, "spec_name": "<spec-name>", "rules_hit": 2, "matched_rules": ["..."] } ]
}

• porting_item_id is <parent_id>__<group> — globally unique, stable, and carries the parent for traceability.
• code_range is a multi-range string (comma-separated) spanning every variant in the group. The existing resolveContext multi-range support (and the dispatcher) already accept this form unchanged.
• Matching runs on a capped body sample of each kernel (first ~60 lines), not the entire kernel, so spec selection stays sharp.

1.4.4 Downstream impact

Decomposition is transparent to every later stage. The matched-YAML, dispatcher contract, tasks.md generation, and verification stages simply see more, smaller, individually-actionable items instead of one giant item. Each group child becomes one porting_item in the matched YAML (§4.4) and one task / one dispatcher invocation in tasks.md (§5.8).

2. Script Initial Screening (Script-based preliminary filtering)

2.1 Run the screening script

Execute the initial screening script against the input YAML:

node skills/easywos-spec/scripts/spec_matcher.js \
  --input <easywos-yaml-path> \
  --specs <combined-spec-summary-yaml-path> \
  --output <candidates-json-path> \
  [--threshold <lines>]   # whole-file asm decompose trigger; default 400
  [--no-decompose]        # disable per-kernel decomposition entirely

2.2 Script behavior

The script performs:

0. Whole-file decomposition (pre-pass): For each porting_item, if it is an assembly file over the threshold (or segment: true), split it into per-kernel group children before matching (see Section 1.4). Each group is then matched independently in the steps below; non-decomposed items follow the original single-context path.

1. Scope pre-classification: For each line in a porting_item's context (resolved from file_path + code_range in step 1.2, or the group body sample for a decomposed group), classify it into one of:

   • instruction — assembly mnemonic line (push, mov, addps, stp, ldr, etc.)
   • declaration / perl_declaration — variable/type declarations
   • intrinsic_call / function_call — lines containing function call patterns
   • preprocessor — #include, #define, etc.
   • directive — assembler directives (.globl, .type, .cfi_*)
   • expression — fallback for all other non-comment lines
   • comment — lines that are purely comments (excluded from matching)

2. Scope-filtered regex matching: For each spec's match_rules, apply the rule's pattern ONLY against lines classified under the rule's declared scope. If scope is not specified, match against all non-comment lines.

3. Candidate list output: For each porting_item, output all specs whose match_rules produced at least one hit, along with rules_hit count.

2.3 Script output format

See references/script-output-format.md for the JSON schema and example.

3. LLM Semantic Refinement (LLM-based final decision)

After receiving the script's candidate output, perform the following analysis for each porting_item that has non-empty matches:

3.1 Refinement input

For each porting_item with candidates, you receive:

• The resolved source code context (from file_path + code_range)
• The candidate spec list with rules_hit and matched_rules
• Each matched rule's declared scope

For a decomposed group child (a candidate carrying parent_id / group / functions), additionally:

• Treat the group as the unit of refinement — it represents one logical kernel family (all size/CPU variants of the same base routine), so a spec that applies to one variant applies to the whole group.
• The matching context is a body sample of each variant, not the full kernel. If a spec's applicability is genuinely uncertain from the sample, resolve the group's code_range against the source file and read more before deciding — do not reject solely because the sample was short.
• Group children inherit semantics / constraints / register_mapping from their parent porting_item (the parent's fields describe the whole file's kernel family); reference the parent when scoring.

3.2 Refinement rules

For each candidate match, verify:

1. Scope correctness: Does the matched pattern appear in the code in a context that genuinely corresponds to the rule's declared scope? A pattern matching in a comment, string literal, or wrong structural context is a false positive — remove it.

2. Semantic relevance: Is the spec's described migration guidance actually applicable to this code? A pattern match on a register name that happens to appear in unrelated logic is not a true match — remove it.

3. Multi-match combination: If multiple specs remain after filtering, determine whether they address different aspects of the same code (→ keep all) or redundantly overlap (→ keep the more specific one).

3.3 Output: port_spec_ids array

After refinement, output for each porting_item:

• port_spec_ids: Array of confirmed spec IDs (sorted ascending), e.g., [3, 5]
• Empty array [] if all candidates were rejected (no spec applies)

3.4 Confidence scoring

For each porting_item, assign:

match_confidence:
  rules_hit: <total rules matched across all confirmed specs>
  scope_verified: <true if LLM confirmed all matches are scope-correct>
  llm_confidence: <"high" | "medium" | "low">

Confidence guidelines:

• high: Multiple rules hit in correct scope, clear semantic match
• medium: 1-2 rules hit, scope is borderline but likely correct
• low: Pattern matched but semantic fit is uncertain, or scope is ambiguous

3.5 Low confidence handling

If llm_confidence: low, flag the item. It will be marked [NEEDS REVIEW] in the generated tasks.md to indicate human verification is recommended.

4. Matched Output File Generation

4.1 Generate the matched YAML

Create a new YAML file that is identical to the input EasyWoS YAML with the following additions to each porting_item:

port_spec_ids: [3, 5]
match_confidence:
  rules_hit: 4
  scope_verified: true
  llm_confidence: high

For unmatched items:

port_spec_ids: []
match_confidence: null

4.2 Output file naming

<original-filename>-matched.yaml

Example: x64-to-arm64-porting.yaml → x64-to-arm64-porting-matched.yaml

4.3 Example output

See references/matched-yaml-example.md for a full example.

4.4 Decomposed group children in the matched YAML

When the screening script decomposed a whole-file item into group children, the matched YAML replaces that one parent item with one porting_item per group child. Each child is a self-contained porting_item:

  - id: <parent_id>__foo
    parent_id: <parent_id>
    group: foo
    title: <parent title> — foo
    file_path: <path/to/kernels.asm>
    code_range: "440-512, 980-1040, 1600-1672"   # multi-range: every variant
    functions: [foo_16x16_sse2, foo_8x8_sse2, ...]
    function_count: 40
    # semantics / constraints / register_mapping: inherit from the parent
    # item, narrowed to this kernel family
    port_spec_ids: [1]
    match_confidence:
      rules_hit: 2
      scope_verified: true
      llm_confidence: high

Rules:

• Keep the parent's semantics, constraints, register_mapping (copied or referenced) so the dispatcher data contract (§6.3) stays complete.
• id MUST be the <parent_id>__<group> form the script emitted — tasks.md and the dispatcher key off it.
• Preserve the code_range multi-range string verbatim from the script output.
• Do NOT also emit the original parent item — it is fully replaced by its children. (If a file produced zero kernels and was therefore not decomposed, the original item is kept as-is.)

5. Tasks.md Generation Guide

When generating tasks.md for an OpenSpec change that involves porting, use the matched YAML output to structure the task list.

5.1 Core logic

For each porting_item in the matched YAML, generate one task entry in tasks.md.

5.2 Task entry format

- [ ] N.M Port `<id>` (<title>) [lines <code_range>] → specs: <port_spec_ids>
  `/dispatcher-skill <id> --specs <comma-separated-ids> --source <matched-yaml-path>`

5.3 Multi-spec matched task

When port_spec_ids has multiple entries:

- [ ] 3.2 Port `addition-logic` (SIMD Addition with Scalar Accumulation) [lines 327-384] → specs: [13, 15]
  `/dispatcher-skill addition-logic --specs 13,15 --source x64-to-arm64-porting-matched.yaml`

The dispatcher MUST combine guidance from all listed specs.

5.4 Unmatched task (llm-freeform)

When port_spec_ids is empty:

- [ ] 3.3 Port `custom-block` (Custom Logic Block) [lines 500-520] → specs: [] (LLM freeform)
  `/dispatcher-skill custom-block --mode llm-freeform --source x64-to-arm64-porting-matched.yaml`

The dispatcher invokes the arm64-baseline-porting skill as constraint framework.

5.5 Low confidence task marking

When match_confidence.llm_confidence is "low":

- [ ] [NEEDS REVIEW] 3.4 Port `ambiguous-block` (Unclear Pattern) [lines 600-620] → specs: [7]
  `/dispatcher-skill ambiguous-block --specs 7 --source x64-to-arm64-porting-matched.yaml`

5.6 Task ordering

Tasks SHALL be ordered according to the porting_items array order in the matched YAML file (which preserves the original EasyWoS scan order). Decomposed group children appear in the parent's original position, in the group order the script emitted, so all kernels of one file remain contiguous.

5.8 Decomposed group child task

A group child generates one task exactly like any other item, keyed by its <parent_id>__<group> id. Surface the function count and group so the task is self-describing, and group all children of one source file under a sub-heading:

### Port path/to/kernels.asm (decomposed: N kernel groups)

- [ ] 3.1 Port `<parent_id>__foo` (foo, 40 fns) [ranges 440-512, 980-1040, ...] → specs: [1]
  `/dispatcher-skill <parent_id>__foo --specs 1 --source <project>-arm64-porting-matched.yaml`
- [ ] 3.2 Port `<parent_id>__bar` (bar, 24 fns) [ranges ...] → specs: [2,4]
  `/dispatcher-skill <parent_id>__bar --specs 2,4 --source <project>-arm64-porting-matched.yaml`

The dispatcher resolves the group child by its id just like a normal item; the multi-range code_range is passed through to the leaf skill as context spanning every variant in the group.

5.7 Verification section

After all dispatcher invocation tasks, append a "Verification" section to tasks.md. The exact V.1–V.3 task wording depends on which flow Section 7 selects (assembly vs intrinsics vs both); V.4 and V.5 are common to both flows.

## Verification

- [ ] V.1 Generate gtest file `test_<name>.cpp` with per-porting-item fixtures and boundary condition tests (see Section 7 for the flow that matches the dispatched outputs)
- [ ] V.2 Generate `CMakeLists.txt` (asm flow: FetchContent gtest + armasm64 custom command; intrinsics flow: FetchContent gtest + test_kernels_<arch>.c static library)
- [ ] V.3 Generate `build_and_compare.bat` (see Section 7.4)
- [ ] V.0 Negative-control gate (per fixture): before trusting any pass, prove each fixture can FAIL — see Section 7.6. A fixture that has never been observed red is not yet a valid check.
- [ ] V.4 Build ARM64: `cmake -S . -B build -A ARM64 && cmake --build build --config Release`
- [ ] V.5 Run tests: execute the gtest binary and verify all tests pass
- [ ] V.6 Per-item verify → retry loop: for any fixture that fails at V.5, write a feedback file and re-dispatch that item with `--feedback` (see Section 8). Retry up to K times; on exhaustion mark the item `[NEEDS REVIEW]` and continue. Only items whose fixtures are green (and were shown red at V.0) are `[x]` done.

V.0 runs before V.4/V.5 in trust order even though the numbering places it after V.3: you cannot believe a green V.5 for a fixture you never watched go red. The build (V.4) must succeed first so the negative control can compile; see §7.6 for the exact procedure.

For the intrinsics flow, V.1 must additionally produce a test_kernels_<arch>.c file with the MSVC compatibility shim block at the top (see references/unit-test-workflow-intrinsics.md — "Test Seam" section). This file IS the unit-under-test; the leaf-skill output .c files are NOT linked into the test binary directly.

6. Skilltree Dispatch Protocol

6.1 Dispatcher 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>

6.2 Multi-spec combination

When --specs contains multiple IDs (e.g., --specs 3,5), the dispatcher MUST:

1. Load spec descriptions for ALL listed IDs from the spec collection
2. Synthesize a combined migration approach using guidance from each spec
3. Pass the combined context to the appropriate leaf skill(s)

6.3 Data contract: dispatcher → leaf skill

The dispatcher passes to the leaf skill:

porting_item:
  id: <porting_item_id>
  file_path: <relative path to source file>
  code_range: <line range in source file>
  context: <source code resolved from file_path + code_range>
  semantics: <semantic description>
  constraints: <ARM64 constraints list>
  register_mapping: <register mapping table>

matched_specs:
  - id: 3
    name: no-movemask
    description: <full spec migration guidance>
  - id: 5
    name: no-zeroupper
    description: <full spec migration guidance>

match_confidence:
  rules_hit: 4
  scope_verified: true
  llm_confidence: high

For --mode llm-freeform, the matched_specs field is empty and the leaf skill MUST load arm64-baseline-porting as its constraint framework.

6.4 Dispatcher routing rules

7. Unit Test Generation Workflow

After the dispatcher executes leaf skills and produces ARM64 output, generate unit tests to verify functional correctness. One test fixture per porting item, using Google Test framework, calling the real ARM64 kernel via a clean C ABI.

Two parallel flows are supported, depending on what the leaf skills produced:

7.1 Assembly flow — for hand-written .asm outputs

Use when at least one dispatched item produced ARM64 assembly (*.asm with EXPORT directives). The test seam is the EXPORTed function itself; armasm64 assembles the .asm to .obj and CMake links it into the test binary.

For detailed workflow, see references/unit-test-workflow.md. CMake template: references/cmake-template.md.

7.2 Intrinsics flow — for C/intrinsic outputs

Use when dispatched items produced C files using <arm_neon.h> / <arm_acle.h> intrinsics. The test seam is a sibling test_kernels_<arch>.c file that re-exposes each SIMD kernel with a clean C ABI (raw integer/pointer types, no project headers); CMake compiles that file as a static library and links it into the test binary. The MSVC ARM64 compatibility shim (<intrin.h> for CRC32, _BitScanForward64 for __builtin_ctzll) is required boilerplate.

For detailed workflow, see references/unit-test-workflow-intrinsics.md. CMake template: references/cmake-template-intrinsics.md.

7.3 Selecting the flow per dispatched item

The dispatcher's source field on each matched spec indicates the leaf-skill family:

If a single tasks.md run produces both kinds of output, generate both test drivers (one binary per language family) — items don't share test seams across the asm/intrinsics boundary.

7.4 Build script (shared)

Both flows use the same build_and_compare.bat driver — see references/build-script-template.md. Substitute <name> with the project's test binary name; the script is identical otherwise.

7.5 Prerequisites

• Windows ARM64 machine (native execution, no emulation) or aarch64 Linux host.
• MSVC toolchain with ARM64 build tools (Visual Studio 2019+) — required for both flows. The asm flow additionally needs armasm64 (ships with MSVC ARM64).
• CMake 3.14+ (for FetchContent).
• Internet access during first build (to fetch Google Test).

7.6 Negative-control gate (prove the test can fail before trusting a pass)

A green test is meaningless until the same fixture has been observed red. A leaf skill can emit an identity stub, a fixture can compare a value against itself, or the kernel may not be linked at all — any of these pass instantly and silently, and the loop then "confidently" converges on broken output. Before any fixture's pass is trusted (V.5), it MUST be shown failing under a deliberately wrong input. This is a mandatory negative control, one per fixture.

Procedure, per fixture, after V.4 build succeeds:

1. Perturb the expected value. In a throwaway build, alter the fixture's reference so the ARM64 result and the reference genuinely disagree — e.g. corrupt one byte of the reference buffer, or assert against ref + 1. Do NOT perturb the kernel under test.
2. Run and confirm RED. The fixture MUST now report failure (non-zero exit / [ FAILED ]). If it still passes, the check is not wired to the kernel — the test is invalid; fix the fixture (wrong seam, comparing self-to-self, kernel not linked) before proceeding. Do not continue on a fixture that refuses to go red.
3. Revert the perturbation and rebuild clean. Only now does a green result at V.5 count as a real pass.

Record which fixtures were shown red. A fixture that passed at V.5 but was never observed red at V.0 is reported as unverified, not as passing — state this plainly rather than claiming correctness that was never failure-tested.

Cheap batch form: a single --gtest_filter run against a build with all references perturbed by +1 should turn the ENTIRE suite red. A suite that stays partly green under global perturbation has dead fixtures — investigate before trusting any of it.

8. Verify → Retry Loop (per-item feedback closure)

Sections 5–7 dispatch each item once and verify the batch once. This section closes the loop: a fixture that fails at V.5 feeds its failure back into the dispatcher so the item is re-ported with knowledge of what broke, instead of a human hand-re-running the command. This is the only feedback edge in the pipeline, and it turns the DAG into a per-item loop:

dispatch(item) → leaf skill → build+gtest ─ green (shown red at V.0) → done [x]
                                          └ red → write feedback → re-dispatch --feedback ↺ (≤ K)
                                                                    └ K exhausted → [NEEDS REVIEW]

8.1 Loop ownership

The orchestrator (this skill's task list) owns the loop: the retry counter, the terminal exit, and writing the feedback file. The dispatcher and leaf skills are stateless executors of a single attempt (dispatcher §2.7). Default retry budget K = 3 per item; tune per project.

8.2 Writing the feedback file

On a V.5 failure for item <id>, write feedback/<id>.attempt<N>.yaml in the schema of dispatcher §2.7.1: capture stage, failure_kind, verbatim truncated detail, failing_fixtures, and — where the cause is diagnosable — a hypothesis. Accumulate prior attempts in prior_attempts so a recurring identical failure is visible to the leaf skill (dispatcher §2.7.2 rule 3).

8.3 Re-dispatch

Re-invoke the same command the item was generated with (§5.2/§5.4), adding --feedback feedback/<id>.attempt<N>.yaml:

- [ ] 3.2r Retry `pixel-sad` (attempt 2/3, prior: SadTest.Block16x16 assertion) → specs: [33,58]
  `/dispatcher-skill pixel-sad --specs 33,58 --source <matched-yaml> --feedback feedback/pixel-sad.attempt2.yaml`

After re-dispatch, re-run only the affected fixtures (--gtest_filter), and re-apply the V.0 negative control to any fixture whose seam changed.

8.4 Terminal exit (no item blocks the batch)

• Pass: fixture green AND shown red at V.0 → mark the item [x].
• Exhausted: K attempts all red → stop retrying, mark [NEEDS REVIEW] with the last feedback file path, continue to the next item. Never let one hard item stall the whole batch.
• Items are independent kernels, so retries for different items may proceed concurrently; the loop is per-item, not a global barrier.