Issue Taxonomy
Reference for categorizing issues found during dogfooding. Read this at the start of a dogfood session to calibrate what to look for.
Contents
Severity Levels
| Severity | Definition |
|---|---|
| critical | Blocks a core workflow, causes data loss, or crashes the app |
| high | Major feature broken or unusable, no workaround |
| medium | Feature works but with noticeable problems, workaround exists |
| low | Minor cosmetic or polish issue |
Categories
Visual / UI
- Layout broken or misaligned elements
- Overlapping or clipped text
- Inconsistent spacing, padding, or margins
- Missing or broken icons/images
- Dark mode / light mode rendering issues
- Responsive layout problems (viewport sizes)
- Z-index stacking issues (elements hidden behind others)
- Font rendering issues (wrong font, size, weight)
- Color contrast problems
- Animation glitches or jank
Functional
- Broken links (404, wrong destination)
- Buttons or controls that do nothing on click
- Form validation that rejects valid input or accepts invalid input
- Incorrect redirects
- Features that fail silently
- State not persisted when expected (lost on refresh, navigation)
- Race conditions (double-submit, stale data)
- Broken search or filtering
- Pagination issues
- File upload/download failures
UX
- Confusing or unclear navigation
- Missing loading indicators or feedback after actions
- Slow or unresponsive interactions (>300ms perceived delay)
- Unclear error messages
- Missing confirmation for destructive actions
- Dead ends (no way to go back or proceed)
- Inconsistent patterns across similar features
- Missing keyboard shortcuts or focus management
- Unintuitive defaults
- Missing empty states or unhelpful empty states
Content
- Typos or grammatical errors
- Outdated or incorrect text
- Placeholder or lorem ipsum content left in
- Truncated text without tooltip or expansion
- Missing or wrong labels
- Inconsistent terminology
Performance
- Slow page loads (>3s)
- Janky scrolling or animations
- Large layout shifts (content jumping)
- Excessive network requests (check via console/network)
- Memory leaks (page slows over time)
- Unoptimized images (large file sizes)
Console / Errors
- JavaScript exceptions in console
- Failed network requests (4xx, 5xx)
- Deprecation warnings
- CORS errors
- Mixed content warnings
- Unhandled promise rejections
Accessibility
- Missing alt text on images
- Unlabeled form inputs
- Poor keyboard navigation (can't tab to elements)
- Focus traps
- Insufficient color contrast
- Missing ARIA attributes on dynamic content
- Screen reader incompatible patterns
Exploration Checklist
Use this as a guide for what to test on each page/feature:
- Visual scan -- Take an annotated screenshot. Look for layout, alignment, and rendering issues.
- Interactive elements -- Click every button, link, and control. Do they work? Is there feedback?
- Forms -- Fill and submit. Test empty submission, invalid input, and edge cases.
- Navigation -- Follow all navigation paths. Check breadcrumbs, back button, deep links.
- States -- Check empty states, loading states, error states, and full/overflow states.
- Console -- Check for JS errors, failed requests, and warnings.
- Responsiveness -- If relevant, test at different viewport sizes.
- Auth boundaries -- Test what happens when not logged in, with different roles if applicable.