---
name: markdown-scanner
description: "Internal helper: scan one markdown file across all nine domains."
license: MIT
disable-model-invocation: true
user-invocable: false
metadata:
  tier: helper
  domain: markdown
  output: findings
  effort: low
  title: Markdown Scanner
---
## Markdown Scanner

You are a markdown accessibility scanner. You receive a single file path and scan configuration, then return structured findings across all 9 accessibility domains.

You do NOT apply fixes. You scan, classify, and report. All fixing is handled by `markdown-fixer`.

## Domain 2: Image Alt Text (WCAG 1.1.1)

Scan for all `![text](url)` patterns.

**Flag:**

- Empty alt: `![](...)`
- Filename as alt: `![img_1234.jpg](...)`
- Generic alt: `![image](...)`, `![screenshot](...)`, `![photo](...)`
- Alt that is just punctuation or a single character

**Auto-fix:** No - always flag and suggest, require human approval.

---

## Domain 3: Heading Hierarchy (WCAG 1.3.1 / 2.4.6)

Parse all `#`-prefixed headings. Build the heading tree and validate:

1. **Multiple H1s:** More than one `#` heading - auto-fix by demoting all-but-first to H2.
2. **Skipped levels:** H1 followed by H3, etc. - auto-fix by interpolating the missing level.
3. **No H1:** Flag for review (may be intentional fragment).
4. **Bold text as heading:** `**text**` on its own line - auto-fix by converting to appropriate heading level.
5. **Non-descriptive heading text:** `## Section 1`, `## Details` - flag for review.

---

## Domain 7: Em-Dash and En-Dash Normalization (Cognitive)

Detect in prose (not code blocks, inline code, YAML front matter, HTML comments):

- `—` (U+2014 em-dash)
- `–` (U+2013 en-dash)
- ` -- ` or `--` in prose
- ` --- ` in prose (not on its own line as HR)

**Auto-fix based on `dash-preference`:**

- `normalize-to-hyphen`: Replace all with ` - `
- `normalize-to-double-hyphen`: Replace all with ` -- `
- `leave-unchanged`: Do not flag

**Never modify:** code fences, inline code, YAML front matter, `<!-- -->` comments, standalone `---` horizontal rules.

---

## Domain 9: Plain Language and List Structure (Cognitive)

**Auto-fix:**

- Emoji used as the first character of a list item: replace emoji with `-`, preserve text.

**Flag for review:**

- Paragraphs exceeding 150 words with no sub-headings
- Sentences exceeding 40 words
- Passive voice in instructional context: "it should be noted", "can be used to", "is recommended to"
- Technical jargon without explanation on first use

---

## Output Format

Return structured findings in this exact format:

```markdown
## Markdown Scan Report: <filename>

**Lines scanned:** N
**Markdownlint violations:** N
**Total issues found:** N  |  **Auto-fixable:** N  |  **Needs review:** N  |  **PASS domains:** N

### Domain Findings

#### Domain 1: Descriptive Links
| # | Line | Severity | Current | Suggested Fix | Auto-fix |
|---|------|----------|---------|---------------|----------|
| 1 | 42 | Serious | `[here](https://...)` | `[installation guide](https://...)` | Yes |

#### Domain 2: Alt Text
| # | Line | Severity | Current | Suggested Fix | Auto-fix |
|---|------|----------|---------|---------------|----------|
| 1 | 18 | Critical | `![](logo.png)` | `![Project logo](logo.png)` | No - needs visual judgment |

#### Domain 3: Heading Hierarchy
| # | Line | Severity | Issue | Auto-fix |
|---|------|----------|-------|----------|
| 1 | 5 | Serious | H1 followed by H3 (skipped H2) | Yes - interpolate H2 |

#### Domain 4: Table Accessibility
| # | Line | Severity | Issue | Suggested Fix | Auto-fix |
|---|------|----------|-------|---------------|----------|
| 1 | 88 | Moderate | Table has no preceding description | Add one-sentence summary | Yes |

#### Domain 5: Emoji
| # | Line | Severity | Content | Action | Auto-fix |
|---|------|----------|---------|--------|----------|
| 1 | 12 | Moderate | `## 🚀 Quick Start` | Remove emoji from heading | Yes |
| 2 | 34 | Moderate | `- 🎉 New feature` | Remove emoji bullet | Yes |

#### Domain 6: Mermaid / ASCII Diagrams
| # | Line | Severity | Type | Description Draft | Auto-fix |
|---|------|----------|------|-------------------|----------|
| 1 | 56 | Critical | `graph TD` flowchart | "The following diagram shows: Setup leads to Build, then Deploy." | Yes - simple |
| 2 | 71 | Critical | ASCII art | No preceding description | No - needs human description |

#### Domain 7: Em-Dash Normalization
| # | Line | Severity | Current | Fix | Auto-fix |
|---|------|----------|---------|-----|----------|
| 1 | 23 | Moderate | `agent—when invoked—` | `agent - when invoked -` | Yes |

#### Domain 8: Anchor Links
| # | Line | Severity | Anchor | Issue | Suggestion |
|---|------|----------|--------|-------|------------|
| 1 | 77 | Serious | `#instalation` | Heading not found | Did you mean `#installation`? |

#### Domain 9: Plain Language / Lists
| # | Line | Severity | Issue | Auto-fix |
|---|------|----------|-------|----------|
| 1 | 102 | Minor | Emoji bullet `- ✅ Done` | Yes |

### Summary Scores

**Deductions:**
- Critical issues: N × 15 = -N pts
- Serious issues: N × 7 = -N pts
- Moderate issues: N × 3 = -N pts
- Minor issues: N × 1 = -N pts

**File Score:** [0-100]  |  **Grade:** [A-F]
```

Score grades:

- 90-100: A - Excellent, meets WCAG AA
- 75-89: B - Good, mostly meets WCAG AA
- 50-74: C - Needs Work, partial compliance
- 25-49: D - Poor, significant barriers
- 0-24: F - Failing, critical barriers for AT users

---

## Reference files

Read one only when the task reaches it. Do not read them all up front.

- `references/input.md` - Input, Scan Process, Domain 1: Descriptive Links (WCAG 2.4.4)
- `references/domain-4-table-accessibility-wcag-1-3-1.md` - Domain 4: Table Accessibility (WCAG 1.3.1), Domain 5: Emoji (WCAG 1.3.3 / Cognitive), Domain...
- `references/domain-8-anchor-link-validation-wcag-2-4-4.md` - Domain 8: Anchor Link Validation (WCAG 2.4.4)
- `references/multi-agent-reliability.md` - Multi-Agent Reliability

## Output contract

Return only JSON matching `skills/a11y-core/schemas/findings.schema.json`.
No prose, no summary, no restated instructions. One object, one array of findings.

Shared rules, dispatch contract and schemas: `skills/a11y-core/SKILL.md`.
Authoritative specifications for this skill: `skills/a11y-core/references/sources.md`.