WCAG Audit Automation

Remediation Ticket Routing

A normalized accessibility violation is not actionable until it lands in front of the one team that can fix it, with the right urgency and without becoming the fortieth duplicate of a defect that has been open for a month. Remediation ticket routing is the ownership-and-workflow layer that turns a deduplicated finding into correctly-owned, correctly-notified work: it resolves which team owns the failing component, decides whether the finding blocks a deploy, opens a backlog item, or fires an alert, and guarantees a recurring violation on a shared header never spawns a new ticket every night. This guide, part of the accessibility compliance baseline for enterprise web ops, covers the routing logic and human process — not the tracker payload mechanics, which live elsewhere.

The failure this page prevents is organizational, not technical. A scanner that reports perfectly and files tickets flawlessly still fails if every ticket lands in a single “Accessibility” backlog that no product team reads, or if the same color-contrast failure on a design-system button opens 300 tickets across 300 routes. Routing is where scan output stops being a report and becomes assigned, tracked, deadline-bearing work. Get the ownership map and the dedupe key right and remediation velocity follows; get them wrong and the whole pipeline produces noise that teams learn to filter out.

Prerequisites & Environment Parity

Routing consumes normalized findings and emits routing decisions. Both ends must be stable before the logic in between can be trusted:

  • A normalized, deduplicated finding stream. Routing assumes each finding already carries a canonical rule_id, a stable CSS selector, a route, and an impact label. That normalization and false-positive filtering is the job of the error categorization and triage pipelines; do not re-litigate rule validity here. Routing trusts the impact it is handed.
  • A version-controlled component ownership map. The single source of truth for “who owns this DOM subtree” is a committed file — path globs, data-owner attributes, or a CODEOWNERS-style table. It ships with the application repo and is reviewed like code. Deriving the team from a selector is detailed in mapping violations to component owners.
  • A tracker client and a notification transport. Routing decides whether and where; the actual Jira/GitHub issue creation — payload shape, field mapping, idempotency keys, transitions — is the concern of the remediation routing from violation to issue tracker guide, which this layer calls into. Alert fan-out to Slack and email is covered in routing accessibility alerts to Slack and email.
  • An agreed severity-to-SLA policy. The impact levels the engine emits (critical, serious, moderate, minor) must map to a documented remediation deadline before routing can attach one. That mapping is a process decision, ratified once and versioned alongside the ownership map.

Treat the ownership map and the SLA policy as infrastructure-as-code. A routing decision made from an uncommitted spreadsheet is unauditable, and an audit will ask you to prove why a given violation went to a given team on a given day.

Conceptual model: the routing pipeline

Routing is a short, ordered pipeline with a single fan-out at the end. Each finding passes through owner resolution, then duplicate suppression, then a severity gate that chooses exactly one disposition. The order is deliberate: resolving the owner first means the dedupe key can be scoped per team, and deduping before the severity gate means a recurring critical finding updates its existing blocking ticket rather than opening a fresh one on every run.

The first stage, owner resolution, takes the finding’s selector and route and walks the component ownership map to produce an owning team plus a default assignee. A finding that resolves to no owner is not dropped — it routes to a designated triage owner so nothing falls silently on the floor.

The second stage, deduplication, computes a stable fingerprint for the defect — canonically (rule_id, normalized_selector, owning_team) — and checks it against open tickets. A match updates the existing ticket (bumps a “still failing” counter, refreshes the last-seen timestamp) instead of creating a new one. This is what stops a shared component’s failure from carpet-bombing the tracker: 300 routes rendering the same broken button collapse to one ticket keyed on the component, not the URL.

The third stage, the severity gate, reads the finding’s impact and the SLA policy and selects one disposition: block the deploy and open a ticket for critical/serious, open a non-blocking backlog ticket with an SLA clock for moderate, or emit an alert without a ticket for minor/informational findings. The gate is where accessibility policy becomes a merge outcome.

From normalized finding to owned, deduplicated, severity-routed disposition A left-to-right flow of three process steps followed by a severity decision that fans out to three terminals. Normalized finding (rule id, selector, impact); Resolve owner (component map); Dedupe (against open tickets). A diamond asks Route by severity. Critical or serious goes to a red terminal Block deploy and open ticket assigned to the owning team; moderate goes to a green terminal Backlog ticket with an SLA clock; minor goes to an indigo terminal Slack or email alert with no ticket. Normalized finding Resolve owner Dedupe rule · selector · impact component map vs open tickets Route by severity critical / serious moderate minor Block deploy · open ticket Backlog ticket · SLA clock Slack / email alert assign to owning team owner queue, deadline set notify only, no ticket

The pipeline is intentionally linear and side-effect-free until the final stage. Owner resolution and dedupe are pure functions over the finding plus the ownership map plus the set of open tickets; only the severity gate writes to the tracker or the notification transport. That separation lets you unit-test every routing decision against fixtures without ever touching a live Jira instance, and it means a routing dry-run can print exactly what would happen before any ticket is created.

Step-by-Step Implementation

The sequence below builds a routing function that is deterministic, testable, and idempotent. Each step is independently verifiable against fixture data.

1. Resolve the owning team

Owner resolution reads the finding’s selector and route and consults the ownership map. The map is ordered most-specific-first; the first matching rule wins. Crucially, an unmatched finding resolves to a sentinel triage owner rather than raising or dropping.

from dataclasses import dataclass

@dataclass(frozen=True)
class Owner:
    team: str
    assignee: str          # default assignee handle for new tickets
    channel: str           # notification channel for this team

TRIAGE = Owner(team="a11y-triage", assignee="a11y-guild", channel="#a11y-triage")

def resolve_owner(finding: dict, ownership_map: list[dict]) -> Owner:
    """Return the owning team for a finding, or the triage sentinel.

    ownership_map is ordered most-specific-first; first match wins so a
    rule for `.checkout .btn` beats a broad `.btn` rule. Never returns None
    — an unowned finding must still be routed somewhere accountable.
    """
    selector = finding["selector"]
    route = finding.get("route", "")
    for rule in ownership_map:
        if _matches(rule, selector, route):
            return Owner(rule["team"], rule["assignee"], rule["channel"])
    return TRIAGE   # gap in the map, not a reason to lose the finding

The _matches helper — glob against the selector, prefix-match against the route, or a lookup on a data-owner attribute captured during the scan — is the subject of mapping violations to component owners. Here, treat it as a black box that answers “does this rule claim this element?”.

2. Compute a stable dedupe fingerprint

The fingerprint is what collapses the same defect across routes and runs into a single ticket. Key it on what makes the defect identical, not what makes the occurrence identical — so the route is deliberately excluded for component-scoped rules and the timestamp never enters the hash.

import hashlib

def fingerprint(finding: dict, owner: Owner) -> str:
    """Stable id for the underlying defect, independent of run or route.

    A shared component failing on 300 routes yields ONE fingerprint, so the
    tracker holds one ticket the owning team can burn down — not 300.
    """
    basis = "|".join([
        finding["rule_id"],                 # e.g. color-contrast
        _canonical_selector(finding["selector"]),  # strip nth-child noise
        owner.team,                         # scope the dedupe per owner
    ])
    return "a11y-" + hashlib.sha1(basis.encode()).hexdigest()[:12]

Excluding the route is a policy choice with a trade-off: it gives one ticket per defect (great for a design-system bug) but hides which routes are affected inside the ticket body rather than in separate tickets. The occurrence list — every route and selector instance — is attached to that single ticket as evidence, so nothing about coverage is lost; only the ticket count shrinks.

3. Look up the open ticket before deciding

Deduplication is a read against the tracker’s existing open tickets keyed by fingerprint. This lookup must precede any create, and its result changes the disposition from “create” to “update”.

def dedupe(fp: str, open_index: dict[str, dict]) -> dict | None:
    """Return the existing open ticket for this fingerprint, if any.

    `open_index` is a fingerprint -> ticket map built once per run from the
    tracker so we make one bulk query, not one lookup per finding.
    """
    return open_index.get(fp)

Build open_index once per routing run by querying the tracker for all open accessibility tickets and indexing them by the fingerprint stored on each (as a label or custom field). One bulk read per run beats one lookup per finding and keeps routing fast at thousands of findings.

4. Apply the severity gate

The gate is the only stage with side effects. It maps impact to a disposition, attaches the SLA deadline, and either updates the existing ticket, creates a new one, or emits an alert. It never blocks on a minor finding and never merely alerts on a critical one.

from datetime import datetime, timedelta, timezone

SLA_DAYS = {"critical": 7, "serious": 14, "moderate": 30, "minor": 90}
BLOCKING = {"critical", "serious"}

def route(finding, owner, existing, tracker, notifier) -> str:
    impact = finding.get("impact") or "minor"
    fp = finding["_fingerprint"]

    if existing:
        # Recurring defect: refresh, do not duplicate.
        tracker.touch(existing["id"], last_seen=datetime.now(timezone.utc),
                      add_occurrence=finding)
        if impact in BLOCKING:
            return "blocked:existing"        # still failing → still blocks
        return "updated"

    due = datetime.now(timezone.utc) + timedelta(days=SLA_DAYS[impact])
    if impact in BLOCKING:
        tracker.create(fp, owner, finding, due=due, priority="high")
        notifier.alert(owner, finding, blocking=True)
        return "blocked:new"                 # gate fails the deploy
    if impact == "moderate":
        tracker.create(fp, owner, finding, due=due, priority="normal")
        return "backlog"                     # ticketed, non-blocking
    notifier.alert(owner, finding, blocking=False)
    return "notified"                        # minor: alert only, no ticket

The tracker calls (create, touch) are thin wrappers over the issue-tracker API; their payload construction, idempotency handling, and field mapping belong to the remediation routing from violation to issue tracker guide. The notifier.alert fan-out to channels is built in routing accessibility alerts to Slack and email.

5. Compose the routing run

Wire the stages into one pass over the run’s findings, building the open-ticket index once and collecting dispositions for the run summary.

def route_run(findings, ownership_map, tracker, notifier) -> dict:
    open_index = tracker.open_by_fingerprint()   # one bulk read
    dispositions = []
    for f in findings:
        owner = resolve_owner(f, ownership_map)
        f["_fingerprint"] = fingerprint(f, owner)
        existing = dedupe(f["_fingerprint"], open_index)
        outcome = route(f, owner, existing, tracker, notifier)
        dispositions.append((f["_fingerprint"], owner.team, outcome))
    return _summarize(dispositions)   # counts per team, per outcome

The returned summary — counts per team and per outcome — is what the deploy gate reads to decide pass/fail and what feeds the compliance reporting dashboards.

Configuration Reference

These are the knobs that govern routing behaviour. All live in version control alongside the ownership map.

Field Type Default Description
ownership_map ordered list of rules required Most-specific-first rules mapping selector/route to a team, assignee, and channel.
triage_owner Owner a11y-triage Sentinel that receives findings no map rule claims, so gaps never drop work.
fingerprint_basis list of fields [rule_id, selector, team] Fields hashed into the dedupe key. Add route to get per-route tickets instead of per-defect.
sla_days map impact→int {7, 14, 30, 90} Remediation deadline per impact level, from ratified policy.
blocking_impacts set {critical, serious} Impact levels that fail the deploy gate and open a high-priority ticket.
backlog_impacts set {moderate} Impact levels that open a non-blocking ticket with an SLA clock.
notify_only_impacts set {minor} Impact levels that emit an alert but create no ticket.
recurrence_reopen boolean true Whether a fingerprint matching a closed ticket reopens it rather than creating a new one.
stale_after_runs int 3 Runs a fingerprint can be absent before its ticket is auto-flagged resolved-pending-verify.

The three impact sets must partition the impact space with no overlap and no gaps; a startup assertion that every emitted impact belongs to exactly one set prevents a finding from silently matching nothing and vanishing.

Verification & Testing

Routing is pure until the gate, so test it as pure logic against fixtures, then verify the side-effecting gate against a mock tracker. Never point verification tests at a live tracker instance.

def test_shared_component_dedupes_to_one_ticket():
    """The same defect on many routes must yield one create, N touches."""
    findings = [
        {"rule_id": "color-contrast", "selector": ".ds-button",
         "route": f"/p/{i}", "impact": "serious"} for i in range(50)
    ]
    tracker, notifier = FakeTracker(), FakeNotifier()
    route_run(findings, DS_MAP, tracker, notifier)
    assert tracker.create_count == 1        # one ticket for the component
    assert tracker.touch_count == 49        # every other occurrence attaches

def test_unowned_finding_goes_to_triage():
    f = {"rule_id": "label", "selector": ".mystery", "route": "/x",
         "impact": "moderate"}
    owner = resolve_owner(f, DS_MAP)
    assert owner.team == "a11y-triage"      # gap routes, never drops

def test_minor_never_blocks():
    f = {"rule_id": "region", "selector": "main", "route": "/",
         "impact": "minor", "_fingerprint": "a11y-x"}
    outcome = route(f, TRIAGE, None, FakeTracker(), FakeNotifier())
    assert outcome == "notified"            # alert only, no ticket, no block

In CI, run a routing dry-run on every pull request: execute route_run against a tracker mock that records intended actions and print the per-team, per-outcome summary as a PR comment. Engineers see exactly which team each new finding would be routed to and whether it would block, before anything is filed. Only the post-merge run against the real tracker actually creates tickets.

Failure Modes & Troubleshooting

Duplicate tickets for one recurring defect. Symptom: the tracker fills with near-identical tickets for the same rule on the same component, one per nightly run. Root cause: the fingerprint includes the timestamp or the full nth-child selector, so no two occurrences hash equal. Fix: canonicalize the selector (strip positional pseudo-classes) and exclude run metadata from the basis, so the defect — not the occurrence — is the dedupe unit.

Everything lands in one backlog nobody reads. Symptom: tickets are created but remediation velocity is zero. Root cause: owner resolution is falling through to the triage sentinel for most findings because the ownership map is sparse. Fix: instrument the share of findings hitting TRIAGE; a rising unowned rate is the signal that the map has drifted behind the component tree. Treat map coverage as a tracked metric, not a one-time setup.

Ambiguous ownership routes to the wrong team. Symptom: a shared-layout violation ping-pongs between two teams who each disown it. Root cause: two map rules match the same selector and ordering is undefined. Fix: enforce most-specific-first ordering and make overlaps a lint error in the map’s own CI; when genuine shared ownership exists, resolve to a designated platform/design-system team rather than either consumer.

A closed ticket reopens as a brand-new one. Symptom: a fixed defect regresses and a fresh ticket appears with no history. Root cause: dedupe only queries open tickets, so a regression after closure misses its ancestor. Fix: with recurrence_reopen enabled, also index recently-closed tickets by fingerprint and reopen rather than recreate, preserving the remediation trail an audit will want.

Stale tickets linger after the fix ships. Symptom: tickets stay open for defects that no longer appear in scans. Root cause: nothing closes a ticket when its fingerprint stops recurring. Fix: track last-seen per fingerprint and auto-flag a ticket resolved-pending-verify after stale_after_runs clean runs, handing a human the final close decision rather than trusting the absence of a finding blindly.

Frequently Asked Questions

How do we handle a violation whose component has no owner in the map?

Route it to a designated triage owner rather than dropping it or raising. The sentinel guarantees the finding is tracked and visible, and a rising share of findings hitting triage is the metric that tells you the ownership map has fallen behind the component tree. Close the gap by adding a map rule, not by special-casing the finding.

Why is the same accessibility defect opening a new ticket on every scan run?

The dedupe fingerprint is unstable — it almost certainly includes the run timestamp or a positional nth-child selector that differs per occurrence. Key the fingerprint on rule id, a canonicalized selector, and the owning team only, and look up existing open tickets by that key before creating. A match should update the ticket, not spawn a sibling.

A layout violation could belong to two teams — how do we route it without a fight?

Make the ownership map most-specific-first and treat overlapping rules as a lint failure in the map’s CI. For genuinely shared surfaces like a global header, resolve ownership to the platform or design-system team that owns the component, not to either feature team that merely renders it. The rule that decides this is data in the map, so the routing is reviewable rather than argued per ticket.

Should a minor finding ever block a deploy?

No. The severity gate reserves blocking for critical and serious impact; minor findings emit an alert with no ticket, and moderate findings open a non-blocking backlog item with an SLA clock. Blocking on minor findings is exactly how a gate loses credibility and gets switched to continue-on-error, at which point it blocks nothing at all.

Where does the actual Jira or GitHub issue get created?

Not here. This layer decides ownership, dedupe, and disposition; the tracker payload construction, idempotency keys, and field mapping live in the issue-tracker routing guide, which the severity gate calls into through a thin client. Keeping the decision separate from the transport lets you unit-test every routing outcome against fixtures without touching a live tracker.