.agents/skills/dogfood/references/issue-taxonomy.md

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
• Categories
• 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.