80 lines
2.7 KiB
Markdown
80 lines
2.7 KiB
Markdown
# 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)
|