specmap - SKILL.md Agent Skill

name: specmap description: Map relationships between a web spec section, its Firefox implementation code, and Web Platform Tests. Use when starting work on a spec feature, checking implementation coverage, or finding which WPTs to enable. argument-hint: "[spec-url-or-fragment] [optional: specific-algorithm]" allowed-tools: - Bash(searchfox-cli:) - Bash(webspec-index:) - Bash(curl:) - Bash(jq:) - Read - Grep - Glob

SpecMap: Spec-Code-WPT Mapping

Spec URL or fragment: $0 Specific algorithm (optional): $1

Step 1: Identify the Spec Target and Read Spec Content

If you have a spec URL (from a bug report, code comment, etc.), query it directly:

webspec-index query 'https://html.spec.whatwg.org/#navigate' --format markdown
webspec-index refs 'https://html.spec.whatwg.org/#navigate'

If you only have a feature name, search for it:

webspec-index search "FEATURE_NAME" --limit 5
webspec-index search "FEATURE_NAME" --spec HTML --limit 5

If the exact fragment is unknown, find it by pattern or by listing sections:

webspec-index anchors '*navigate*' --spec HTML
webspec-index list HTML

For WebIDL interface definitions (not provided by webspec-index), use the spec shortname (visible in search results or derivable from the URL hostname/path):

curl -s "https://w3c.github.io/webref/ed/idl/SHORTNAME.idl"

Step 2: Query Searchfox for References

Use searchfox-cli to find files referencing the spec section, split by file type:

# Implementation code (excludes test and generated files)
searchfox-cli -q "DOMAIN.*#FRAGMENT" --only-normal -l 200
searchfox-cli -q "#FRAGMENT" --only-normal --path "dom\|html\|layout\|widget" -l 200
searchfox-cli --id InterfaceName --only-normal -l 100

# Test files only
searchfox-cli -q "DOMAIN.*#FRAGMENT" --only-tests -l 200
searchfox-cli -q "#FRAGMENT" --only-tests -l 200

If results are sparse, try alternative fragment spellings or the IDL interface/method name from the webref IDL extract. If results are too broad, narrow with --path.

Step 3: Analyze Gaps

Cross-reference the webref algorithm steps from Step 1 against the searchfox results from Step 2 to identify:

Spec steps with no corresponding implementation code
Spec steps with implementation but no test coverage in WPT
WPT tests that are currently failing or disabled

WPT is the preferred test location for web platform features. Do NOT flag the absence of Mozilla-specific tests (mochitest, browser-chrome, etc.) as a gap when there is adequate WPT coverage. Mozilla tests are only expected for Firefox-specific behavior that WPT cannot cover (e.g. chrome-privileged APIs, internal pref gating, process architecture).

To check WPT status, look for .ini expectation files using dedicated tools (avoid bash loops which trigger permission prompts):

Use Glob to find .ini files: testing/web-platform/meta/PATH/*.ini
For each .ini file found, use Grep with output_mode: "count" to count expected: and disabled: lines.

No .ini file means the test fully passes. An .ini with disabled: lines means skipped tests. Count expected: lines for the number of non-default expectations.

Step 4: Present the Map

Output a structured report:

## SpecMap: [Feature Name]
Spec: [full spec URL with fragment]

### Implementation Code
| File | Function/Class | Line | Notes |
|------|---------------|------|-------|
| dom/Foo.cpp | Foo::Bar() | 123 | Step 4 of algorithm |

### Web Platform Tests
| Test File | Status | Tests |
|-----------|--------|-------|
| .../feature.html | PASS (no .ini) | 12 subtests |
| .../feature-edge.html | PARTIAL (.ini has 3 expected fails) | 8 subtests |

### Mozilla Tests
| Test File | Type | Notes |
|-----------|------|-------|
| dom/tests/mochitest/test_feature.html | mochitest | ... |

### Coverage Summary
- Spec steps with implementation: N/M
- WPT files found: N (K passing, J partial, L failing)
- Gaps: [list spec steps or areas with no code or test coverage]

Split test results: files under testing/web-platform/ are WPT, other test files are Mozilla tests (mochitest, browser-chrome, xpcshell).

Step 5: Offer to Add Missing References

If implementation code lacks a spec URL comment or step annotations, offer to add them. Ask for confirmation before making edits. Before inserting any spec URL, verify the anchor exists:

webspec-index exists 'SHORTNAME#FRAGMENT' && echo "valid"
# e.g.:
webspec-index exists 'HTML#navigate' && echo "valid"

Examples of references to add:

// https://spec.example.org/#section at the top of an implementing function
// Step N. comments for algorithm implementations
Spec URL references in .webidl files next to interface/method definitions

Tips

WHATWG fragments follow patterns: #dom-interface-method, #the-element-name-element, #concept-name
Firefox code references specs as // https://html.spec.whatwg.org/#fragment or // Step N of https://...
When a spec URL is in a code comment, you can pass it directly to webspec-index query 'URL' to read the referenced section