Spaces:
Sleeping
Sleeping
| # Workflow — Fixing a Bug | |
| ## Purpose | |
| Read this file every time you need to fix a bug. | |
| Follow steps in order. Do not open files not mentioned in the log. | |
| --- | |
| ## Core Principle | |
| **The log tells you where to look. Trust the log. Check one file.** | |
| Do not scan the codebase. Do not refactor while fixing. | |
| --- | |
| ## Step 1 — Read the Error First | |
| Before touching any code: | |
| - [ ] Read `logs/errors.log` — find the exact error entry | |
| - [ ] Identify: file, function, reason, fix hint from the log | |
| - [ ] Read `docs/learnings.md` — has this failed before? | |
| - [ ] If yes → apply the known fix, skip to Step 5 | |
| Error log format to look for: | |
| [ERROR] [timestamp] [file:function] — reason — fix hint | |
| --- | |
| ## Step 2 — Isolate Before Fixing | |
| State this out loud before touching code: | |
| Error in: [file:function] | |
| Reason: [from log] | |
| Fix hint: [from log] | |
| Only file I will open: [file] | |
| - [ ] Open only the file named in the log | |
| - [ ] Find only the function named in the log | |
| - [ ] Do not open any other file unless the log explicitly points there | |
| --- | |
| ## Step 3 — Understand the Failure | |
| Inside the identified function: | |
| - [ ] Check what input is coming in | |
| - [ ] Check where exactly it breaks (line from log) | |
| - [ ] Check if it is a null/undefined issue | |
| - [ ] Check if it is an auth/session issue | |
| - [ ] Check if it is a Supabase RLS issue | |
| - [ ] Reference `docs/debugging.md` → Supabase Specific Errors table | |
| --- | |
| ## Step 4 — Write the Fix | |
| - [ ] Fix only the broken logic | |
| - [ ] Do not rename variables or restructure the function | |
| - [ ] Do not fix adjacent code that looks messy | |
| - [ ] Add or improve error handling inline if it was missing | |
| - [ ] Confirm fix hint from log is addressed | |
| --- | |
| ## Step 5 — Write or Update the Test | |
| - [ ] Find the existing test file for this feature | |
| - [ ] If the failing case was not covered → add a test for it now | |
| - [ ] The test must reproduce the exact failure condition | |
| - [ ] Run only the test for this file first: | |
| ```bash | |
| npm test -- tests/unit/[feature-name].test.ts 2>&1 | tee logs/test.log | |
| ``` | |
| - [ ] Confirm it passes before running full suite | |
| --- | |
| ## Step 6 — Run Full Test Suite | |
| ```bash | |
| bash scripts/test.sh | |
| ``` | |
| - [ ] All tests pass | |
| - [ ] No previously passing test is now failing | |
| - [ ] If a new failure appears → treat it as a new bug, do not chain fixes | |
| --- | |
| ## Step 7 — Update Docs | |
| - [ ] Add one-liner to `docs/progress.md` under the feature | |
| - [ ] If this was a repeated failure or needed a workaround → add to `docs/learnings.md` | |
| - [ ] Append one line to `session/phase-log.md` | |
| - [ ] Update `session/summary.md` | |
| --- | |
| ## Step 8 — Git Commit Message | |
| Provide one-liner commit message in this format: | |
| fix([scope]): [what was broken and what fixed it] | |
| Examples: | |
| fix(auth): handle null session before calling fetchUser | |
| fix(dashboard): return empty array instead of null on no results | |
| fix(db): add missing RLS policy for users table select | |
| **Do NOT push to GitHub. Hand the message to the user.** | |
| --- | |
| ## Step 9 — Confirm with User | |
| - [ ] Show exactly what was changed and in which file | |
| - [ ] Show test results | |
| - [ ] Show commit message | |
| - [ ] Ask: "Confirmed fixed — ready to continue?" | |
| - [ ] Do NOT proceed until user confirms | |
| --- | |
| ## Bugfix Decision Tree | |
| Error occurs | |
| │ | |
| ▼ | |
| Read logs/errors.log | |
| │ | |
| ├── Entry found → go to Step 2 | |
| │ | |
| └── No entry → add logging first, reproduce error, then fix | |
| │ | |
| ▼ | |
| Check docs/learnings.md | |
| │ | |
| ├── Known issue → apply fix directly | |
| │ | |
| └── New issue → isolate → fix → document | |
| --- | |
| ## Common Bug Patterns | |
| | Symptom | Likely Cause | Where to Look | | |
| |---------|-------------|---------------| | |
| | Function returns null unexpectedly | Missing null check on input | The function's first few lines | | |
| | Supabase returns empty data | RLS policy blocking query | Supabase Dashboard → Policies | | |
| | Auth token errors | Session not refreshed | auth handler file | | |
| | Test passes locally, fails in CI | Env var missing in CI | .env setup + CI config | | |
| | Infinite re-render in React | useEffect dependency missing | The specific component file | | |
| | Type error at runtime | TypeScript type not enforced at boundary | Input validation of the function | | |
| --- | |
| ## What NOT to Do | |
| - Do not open the entire codebase to find the bug | |
| - Do not fix multiple bugs in one session without separate commits | |
| - Do not refactor while fixing — fix first, refactor separately | |
| - Do not skip updating the test file | |
| - Do not push to GitHub | |
| - Do not chain fixes — one bug, one fix, one commit |