bug-reporting

Name: bug-reporting
Author: mgifford

27stars2forks

How to install bug-reporting?

mgifford/accessibility-skills/bug-reporting

$npx -y skills add mgifford/accessibility-skills --skill bug-reporting

Installs into the current project.

Summary

Load this skill whenever you are filing, reviewing, or generating accessibility bug reports — whether from automated tool output, manual testing, user reports, or testing with disabled people. The purpose of this skill is to make accessibility findings easier to report accurately

Files · 1

View on GitHub

SKILL.md

1	# Accessibility Bug Reporting Skill
2
3	> Canonical source: `examples/ACCESSIBILITY_BUG_REPORTING_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
4	> This skill is derived from that file. When in doubt, the example is authoritative.
5
6	Apply these rules when filing, reviewing, or generating accessibility bug reports
7	from any source — automated tool output, manual testing, user reports, or
8	testing with disabled people.
9
10	---
11
12	## Core Mandate
13
14	A useful report lets another person understand the barrier, identify the
15	people affected, reproduce it when possible, judge its impact, identify the
16	responsible source, and verify the correction. Not every field applies to
17	every finding — **do not delay a valid report because a selector, tool rule,
18	WCAG mapping, or code-level fix is unavailable.**
19
20	Principles:
21	1. Describe the barrier before the standard — state what task or interaction fails and under what conditions
22	2. Identify the people affected — describe access needs/interaction methods/AT when evidence supports it; never infer a diagnosis or imply one person represents an entire disability group
23	3. State the evidence basis — distinguish user reports, testing with disabled people, manual evaluation, automated results, and reasoned inference
24	4. Record observed facts separately from assumptions, suspected causes, and suggested fixes
25	5. Use complementary testing methods — automated, manual, and testing-with-disabled-people answer different questions; none substitutes for the others
26	6. Collect only relevant context — browser/AT/viewport/preferences matter only when they affect the result
27	7. Protect people and systems — remove personal data, credentials, tokens, and private content from every attachment
28	8. Treat tool output as evidence, not a conformance decision
29	9. Separate severity from priority — task impact and workaround quality inform severity; reach, frequency, deadlines, and business context inform priority
30	10. Fix the source when possible — a shared-component/template/token fix is usually safer than many page-specific patches
31	11. Close with verification evidence — a code change, automated pass, or visual check alone may not prove the user-facing barrier is gone
32
33	---
34
35	## Terminology
36
37	\| Term \| Meaning \|
38	\| --- \| --- \|
39	\| Finding \| An observed or suspected accessibility barrier or test result \|
40	\| Issue \| Tracked work that may contain one or more related findings \|
41	\| Occurrence \| One place or state in which a finding appears \|
42	\| Root cause \| The source producing one or more occurrences (e.g., a shared component) \|
43	\| Affected people \| People whose task/experience is confirmed or reasonably expected to be affected — describe only as specifically as the evidence allows \|
44	\| Manual accessibility evaluation \| Human evaluation using relevant inputs/settings/AT — distinct from testing with disabled people \|
45	\| Testing with disabled people \| Disabled participants using representative tasks, providing evidence from lived experience \|
46	\| Conformance conclusion \| A conclusion about a defined scope, standard, level, and evaluation method \|
47
48	**A failed automated rule does not automatically prove a WCAG failure. A
49	passed automated rule does not prove conformance.** Confirm the result and
50	its scope before making a conformance claim.
51
52	---
53
54	## Severity Scale (this skill)
55
56	\| Severity \| Definition \|
57	\| --- \| --- \|
58	\| Blocker \| A core task cannot be completed, or there's a serious safety/privacy/data-loss risk, with no reasonable workaround \|
59	\| Major \| A task fails, is unreliable, or requires a substantial workaround \|
60	\| Moderate \| The task remains possible but requires significant extra effort or assistance \|
61	\| Minor \| Localized friction without material task loss \|
62	\| Needs review \| The result or impact has not been confirmed \|
63
64	This is an example scale, not a universal standard — calibrate locally with
65	disabled people and product teams, and document local definitions.
66
67	**Severity, priority, reach, frequency, and confidence answer different
68	questions** — do not conflate them:
69
70	\| Field \| Question \|
71	\| --- \| --- \|
72	\| Severity \| How serious is the task-level consequence in this occurrence? \|
73	\| Priority \| When should the team address it? \|
74	\|

People who liked this also viewed

6 picks

Type

bug-reporting

27stars2forks

View on GitHub

How to install bug-reporting?

mgifford/accessibility-skills/bug-reporting

$npx -y skills add mgifford/accessibility-skills --skill bug-reporting

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Accessibility Bug Reporting Skill
2
3	> Canonical source: `examples/ACCESSIBILITY_BUG_REPORTING_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
4	> This skill is derived from that file. When in doubt, the example is authoritative.
5
6	Apply these rules when filing, reviewing, or generating accessibility bug reports
7	from any source — automated tool output, manual testing, user reports, or
8	testing with disabled people.
9
10	---
11
12	## Core Mandate
13
14	A useful report lets another person understand the barrier, identify the
15	people affected, reproduce it when possible, judge its impact, identify the
16	responsible source, and verify the correction. Not every field applies to
17	every finding — **do not delay a valid report because a selector, tool rule,
18	WCAG mapping, or code-level fix is unavailable.**
19
20	Principles:
21	1. Describe the barrier before the standard — state what task or interaction fails and under what conditions
22	2. Identify the people affected — describe access needs/interaction methods/AT when evidence supports it; never infer a diagnosis or imply one person represents an entire disability group
23	3. State the evidence basis — distinguish user reports, testing with disabled people, manual evaluation, automated results, and reasoned inference
24	4. Record observed facts separately from assumptions, suspected causes, and suggested fixes
25	5. Use complementary testing methods — automated, manual, and testing-with-disabled-people answer different questions; none substitutes for the others
26	6. Collect only relevant context — browser/AT/viewport/preferences matter only when they affect the result
27	7. Protect people and systems — remove personal data, credentials, tokens, and private content from every attachment
28	8. Treat tool output as evidence, not a conformance decision
29	9. Separate severity from priority — task impact and workaround quality inform severity; reach, frequency, deadlines, and business context inform priority
30	10. Fix the source when possible — a shared-component/template/token fix is usually safer than many page-specific patches
31	11. Close with verification evidence — a code change, automated pass, or visual check alone may not prove the user-facing barrier is gone
32
33	---
34
35	## Terminology
36
37	\| Term \| Meaning \|
38	\| --- \| --- \|
39	\| Finding \| An observed or suspected accessibility barrier or test result \|
40	\| Issue \| Tracked work that may contain one or more related findings \|
41	\| Occurrence \| One place or state in which a finding appears \|
42	\| Root cause \| The source producing one or more occurrences (e.g., a shared component) \|
43	\| Affected people \| People whose task/experience is confirmed or reasonably expected to be affected — describe only as specifically as the evidence allows \|
44	\| Manual accessibility evaluation \| Human evaluation using relevant inputs/settings/AT — distinct from testing with disabled people \|
45	\| Testing with disabled people \| Disabled participants using representative tasks, providing evidence from lived experience \|
46	\| Conformance conclusion \| A conclusion about a defined scope, standard, level, and evaluation method \|
47
48	**A failed automated rule does not automatically prove a WCAG failure. A
49	passed automated rule does not prove conformance.** Confirm the result and
50	its scope before making a conformance claim.
51
52	---
53
54	## Severity Scale (this skill)
55
56	\| Severity \| Definition \|
57	\| --- \| --- \|
58	\| Blocker \| A core task cannot be completed, or there's a serious safety/privacy/data-loss risk, with no reasonable workaround \|
59	\| Major \| A task fails, is unreliable, or requires a substantial workaround \|
60	\| Moderate \| The task remains possible but requires significant extra effort or assistance \|
61	\| Minor \| Localized friction without material task loss \|
62	\| Needs review \| The result or impact has not been confirmed \|
63
64	This is an example scale, not a universal standard — calibrate locally with
65	disabled people and product teams, and document local definitions.
66
67	**Severity, priority, reach, frequency, and confidence answer different
68	questions** — do not conflate them:
69
70	\| Field \| Question \|
71	\| --- \| --- \|
72	\| Severity \| How serious is the task-level consequence in this occurrence? \|
73	\| Priority \| When should the team address it? \|
74	\|

People who liked this also viewed

6 picks

Type