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

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

Bug Report Format

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

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

2.7 KiB Raw Blame History