| name | mx-api-feature-audit |
| description | Use this skill to audit which MusicXML features the `mx::api` public layer supports, compared to the test corpus and the MusicXML specification. It finds (1) enum bugs -- values present in `mx::core` (and the spec) but missing from the parallel `mx::api` enum, which are silently dropped -- and (2) feature gaps -- elements/attributes used in real-world files that `mx::api` does not expose. It emits `data/api.features.xml` and a prioritized recommendation report. Invoke for requests like "audit mx::api coverage", "what MusicXML features are we missing", "find enum bugs", or "what should we add to the api next".
|
| argument-hint | <optional: a feature/element to focus on> |
| disable-model-invocation | false |
| user-invocable | true |
mx::api Feature Audit
mx::api is a deliberate subset of MusicXML. This skill produces an evidence-based picture of
what that subset covers so we can decide what to add next and which silent-data-loss bugs to fix.
The three views
The audit compares three views of the MusicXML feature surface. A "feature" is an element plus the
attribute names that appear on it.
- Specification -- approximated by
data/synthetic/, which is built to exercise every
element/attribute/enum symbol of MusicXML 3.0/3.1/4.0. In data/corpus.xml these are the
synthetic-files. Treat "appears in a synthetic file" as "is in the spec".
- Corpus (wild) -- the real-world files under
data/ (everything not in synthetic/). In
data/corpus.xml these are the wild-files, and their counts tell you how common a feature is
in practice.
mx::api -- what the public layer actually exposes, which you audit from source in this skill
and record in data/api.features.xml.
data/corpus.xml and the per-file data/**/*.features.xml sidecars are produced by the
python3 -m audit tool (see audit/README.md). They give you views 1 and 2 for free. Your job is
view 3 and the comparison.
Two kinds of finding
- BUG (silent data loss): a value exists in a
mx::core enum but the parallel mx::api enum lacks
it, so the mx::impl reader maps it to a fallback (unspecified/otherX) and the original value
is lost on round-trip. See Step 2.
- GAP (unsupported feature): an element or attribute that
mx::api simply does not model. This is
by design for obscure features, but a gap in a heavily-used wild feature is a candidate to add.
See Step 3.
A worked BUG example you can confirm today: core::AccidentalValue::other has no api::Accidental
member (recorded in data/api.features.xml as status="missing-members"). That is the exact failure
mode Step 2 hunts for.
Procedure
Run the steps in order. Each writes its output to a known location so the next can consume it.
- Step 1 -- refresh the corpus views. See
./steps/step-1-refresh-corpus.md
- Step 2 -- hunt enum bugs (
mx::core vs mx::api). See ./steps/step-2-audit-enums.md
- Step 3 -- audit element/attribute support, write
data/api.features.xml. See
./steps/step-3-audit-elements.md
- Step 4 -- write the prioritized recommendation report. See
./steps/step-4-recommend.md
The data/api.features.xml output format (a superset of the per-file <feature-audit> shape) is
specified in ./resources/api-features-format.md.
Read AGENTS.md (repo root) for the layer map, and the mx-api-add-feature skill for how to
actually implement anything this audit recommends.
