# Workflow & Context Gathering

## Specs First

Before making changes to any feature area, **always check `.kiro/specs/` for related spec folders first**. Specs contain the original requirements, design decisions, architecture diagrams, data models, and task breakdowns that informed the implementation. They provide critical context about:

- Why a feature was built a certain way
- What data models and API contracts were agreed upon
- What correctness properties must hold
- What edge cases were considered

Even if the code has evolved since the spec was written, the spec is the starting point for understanding intent.

## Spec Folder Structure

Each spec folder typically contains:

- `requirements.md` — user stories and acceptance criteria
- `design.md` — architecture, data models, API contracts, error handling
- `tasks.md` — implementation task breakdown with completion status

## When to Check Specs

- Fixing bugs in a feature area — check the spec to understand intended behavior
- Adding to an existing feature — check the spec to understand design constraints
- Investigating unexpected behavior — the spec documents what "correct" looks like
- Refactoring — the spec documents which properties must be preserved

---

## Bug Fix Documentation

When fixing something that is or could be considered a bug, document it with a bug report.

### Process

1. Fix the bug and commit to `master`
2. Push to both `origin` and `backup` remotes
3. Stash any uncommitted work: `git stash`
4. Switch to the `ops/records` branch: `git checkout ops/records`
5. Add a bug report under `docs/bug-reports/` with the naming convention `<area>-<short-description>-<YYYY-MM-DD>.md`
6. Commit and push on `ops/records` to both `origin` and `backup`
7. Switch back to `master`: `git checkout master`
8. Restore specs (gitignored on master, wiped by branch switch): `git checkout ops/records -- .kiro/specs/` then `git reset HEAD .kiro/specs/`
9. Pop stash: `git stash pop`

### Bug Report Format

Each bug report follows the **Symptom, Cause, Fix** pattern per bug:

```markdown
# <Title> — <Date>

## Summary
One paragraph describing the scope and root cause category.

**Commit:** `<hash>` on `master`

---

## Bug N: <Short Title>

**Symptom:** What the user sees or experiences.

**Cause:** The underlying technical reason.

**Fix:** What was changed and why it resolves the issue.

**Files changed:**
- `path/to/file.js`
```

### What Qualifies as a Bug

- Incorrect data display (wrong values, wrong format)
- UI crashes or blank pages (unhandled exceptions)
- Features that stopped working after a migration or refactor
- Missing scope/filter application that was designed but not wired up
- Regressions from dependency or platform changes (e.g., SQLite to PostgreSQL)