Writing Issues That Get Good Results

The quality of what agents build is directly proportional to the quality of the issue. Agents start every session with zero context — your issue IS their context.

Issue Template

Title: [action verb] [what] [in/to where]
# Good: "Add export button to results table"
# Bad:  "Export feature"

## What
1-2 sentences on what this should do from the user's perspective.

## Why
What is missing or broken today. Why this matters.

## Acceptance Criteria
- [ ] Specific, testable condition
- [ ] Another condition
- [ ] Edge case handled

## Notes (optional)
Constraints, files to focus on, patterns to follow.

Issue Type Guide

Type	Use for	What the agent produces
Feature	Net new user-facing capability	Spec + implementation + E2E test file
Bug	Something broken or wrong	Spec with repro steps + fix
Chore	Maintenance, no user-facing change	Spec + targeted changes, no E2E

The system auto-classifies based on your issue content. To force a type, include it in the body: "This is a chore to..." or "This is a bug where..."

Good Issue Examples

Feature

Title: Add CSV export to the reports table

## What
Users need to download report data as CSV to import into spreadsheet tools.
Add an "Export CSV" button to the reports table header.

## Why
Currently, the only way to extract data is copy-paste. Three clients have
requested CSV export this month.

## Acceptance Criteria
- [ ] "Export CSV" button appears in reports table header
- [ ] Clicking downloads a .csv file named "reports-YYYY-MM-DD.csv"
- [ ] CSV includes all visible columns in the current filter state
- [ ] Works with up to 10,000 rows
- [ ] Button is disabled while data is loading

## Notes
Follow the existing pattern in src/components/DataTable.tsx

Bug

Title: Fix: search results show duplicate entries when filter is active

## What
When a text filter is active and the user searches, results appear twice.
Expected: unique results only.

## Why
This is broken today. Affects all users who use both search and filter.

## Acceptance Criteria
- [ ] Search results show each item once regardless of filter state
- [ ] Bug is reproducible: apply any category filter, then search "test"

## Notes
Likely in src/hooks/useSearch.ts — filter and search results are being
merged without deduplication.

Chore

Title: Migrate auth module from deprecated firebase/auth v8 to v9 modular API

## What
This is a chore to update the auth module to use Firebase v9's modular API.
No user-facing changes.

## Why
firebase v8 is deprecated and causes 14 npm audit warnings. v9 modular API
reduces bundle size by ~30%.

## Acceptance Criteria
- [ ] All imports in src/auth/ use v9 modular syntax
- [ ] All tests pass
- [ ] Bundle size does not increase

## Notes
Migration guide: firebase.google.com/docs/auth/web/start

Common Mistakes

Mistake	Problem	Fix
Vague title: "Login page"	No verb, no scope	"Fix: login button unresponsive on mobile Safari"
No acceptance criteria	Agent can't know when it's done	Add 3-5 specific, testable conditions
Missing "why"	Agent prioritizes wrong things	Explain what's broken or missing today
Too large scope	Agent loses focus	Break into 2-3 smaller issues
Ambiguous constraints	Agent makes wrong assumptions	Add notes: "follow pattern in src/..."

Title Patterns That Work

# Features
Add [thing] to [location]
Implement [capability] for [user type]

# Bugs
Fix: [symptom] when [condition]
Fix: [component] fails to [expected behavior]

# Chores
Migrate [thing] from [old] to [new]
Refactor [module] to [pattern]
Update [dependency] to [version]
Remove [deprecated thing]