1# Issue Taxonomy
2 
3Reference for categorizing issues found during dogfooding. Read this at the start of a dogfood session to calibrate what to look for.
4 
5## Contents
6 
7- [Severity Levels](#severity-levels)
8- [Categories](#categories)
9- [Exploration Checklist](#exploration-checklist)
10 
11## Severity Levels
12 
13| Severity | Definition |
14|----------|------------|
15| **critical** | Blocks a core workflow, causes data loss, or crashes the app |
16| **high** | Major feature broken or unusable, no workaround |
17| **medium** | Feature works but with noticeable problems, workaround exists |
18| **low** | Minor cosmetic or polish issue |
19 
20## Categories
21 
22### Visual / UI
23 
24- Layout broken or misaligned elements
25- Overlapping or clipped text
26- Inconsistent spacing, padding, or margins
27- Missing or broken icons/images
28- Dark mode / light mode rendering issues
29- Responsive layout problems (viewport sizes)
30- Z-index stacking issues (elements hidden behind others)
31- Font rendering issues (wrong font, size, weight)
32- Color contrast problems
33- Animation glitches or jank
34 
35### Functional
36 
37- Broken links (404, wrong destination)
38- Buttons or controls that do nothing on click
39- Form validation that rejects valid input or accepts invalid input
40- Incorrect redirects
41- Features that fail silently
42- State not persisted when expected (lost on refresh, navigation)
43- Race conditions (double-submit, stale data)
44- Broken search or filtering
45- Pagination issues
46- File upload/download failures
47 
48### UX
49 
50- Confusing or unclear navigation
51- Missing loading indicators or feedback after actions
52- Slow or unresponsive interactions (>300ms perceived delay)
53- Unclear error messages
54- Missing confirmation for destructive actions
55- Dead ends (no way to go back or proceed)
56- Inconsistent patterns across similar features
57- Missing keyboard shortcuts or focus management
58- Unintuitive defaults
59- Missing empty states or unhelpful empty states
60 
61### Content
62 
63- Typos or grammatical errors
64- Outdated or incorrect text
65- Placeholder or lorem ipsum content left in
66- Truncated text without tooltip or expansion
67- Missing or wrong labels
68- Inconsistent terminology
69 
70### Performance
71 
72- Slow page loads (>3s)
73- Janky scrolling or animations
74- Large layout shifts (content jumping)
75- Excessive network requests (check via console/network)
76- Memory leaks (page slows over time)
77- Unoptimized images (large file sizes)
78 
79### Console / Errors
80 
81- JavaScript exceptions in console
82- Failed network requests (4xx, 5xx)
83- Deprecation warnings
84- CORS errors
85- Mixed content warnings
86- Unhandled promise rejections
87 
88### Accessibility
89 
90- Missing alt text on images
91- Unlabeled form inputs
92- Poor keyboard navigation (can't tab to elements)
93- Focus traps
94- Insufficient color contrast
95- Missing ARIA attributes on dynamic content
96- Screen reader incompatible patterns
97 
98## Exploration Checklist
99 
100Use this as a guide for what to test on each page/feature:
101 
1021. **Visual scan** -- Take an annotated screenshot. Look for layout, alignment, and rendering issues.
1032. **Interactive elements** -- Click every button, link, and control. Do they work? Is there feedback?
1043. **Forms** -- Fill and submit. Test empty submission, invalid input, and edge cases.
1054. **Navigation** -- Follow all navigation paths. Check breadcrumbs, back button, deep links.
1065. **States** -- Check empty states, loading states, error states, and full/overflow states.
1076. **Console** -- Check for JS errors, failed requests, and warnings.
1087. **Responsiveness** -- If relevant, test at different viewport sizes.
1098. **Auth boundaries** -- Test what happens when not logged in, with different roles if applicable.
110