# 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-levels)
- [Categories](#categories)
- [Exploration Checklist](#exploration-checklist)

## 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:

1. **Visual scan** -- Take an annotated screenshot. Look for layout, alignment, and rendering issues.
2. **Interactive elements** -- Click every button, link, and control. Do they work? Is there feedback?
3. **Forms** -- Fill and submit. Test empty submission, invalid input, and edge cases.
4. **Navigation** -- Follow all navigation paths. Check breadcrumbs, back button, deep links.
5. **States** -- Check empty states, loading states, error states, and full/overflow states.
6. **Console** -- Check for JS errors, failed requests, and warnings.
7. **Responsiveness** -- If relevant, test at different viewport sizes.
8. **Auth boundaries** -- Test what happens when not logged in, with different roles if applicable.