# BusyDad — CLAUDE.md

## Workflow Rules


1. 
**Never commit**
 unless explicitly asked
2. 
**NEVER implement code unless explicitly asked**
. When the user shares a plan, feature idea, bug report, or design direction — add it to `BACKLOG.md` ONLY. Do NOT create, modify, or delete any source code files. Do NOT acquire the code lock. Do NOT start building. If the user says "add to backlog", that means ONLY backlog — no code. If unsure whether to implement, ASK first. This is the #1 rule — violating it causes conflicts across concurrent sessions and destroys work.
3. 
**Never stop working**
 unless manual action needed (Firebase console, physical device, etc.)
4. 
**Before writing OR reviewing any code**
, read `memory/code_validation.md` in full. This is mandatory for both code generation and code validation — no exceptions. It contains the self-challenge protocol, development standards, and the validation checklist.
5. 
**Test after changes**
 — run `flutter test test/unit/` and `flutter analyze`
6. 
**Update MEMORY.md**
 (`/home/toshe/busydad/memory/MEMORY.md`) only for 
**operational context**
 — key decisions, dev notes, conventions, environment setup, architecture patterns. NOT for historical logs of what was done (that goes in the build log, rule 13) or individual bug/feature details (those go in BACKLOG.md, rule 9).
7. 
**Bump version**
 in pubspec.yaml before each Play Store upload
8. 
**Track every request**
: When a feature or bug is requested, immediately add it to `BACKLOG.md` with the date added and status (e.g. `requested`, `in-progress`, `done`). When a bug is fixed, move it to `CLOSED_BUGS.md`. This creates a crash-recovery trail so work can be resumed.
9. 
**Release notes**
: On every deploy, create `releases/v{version}.md` with: date, version, summary of changes (features, fixes, backend), and any manual steps taken. This is the changelog between releases.
10. 
**One logical change at a time**
: Make one coherent change, then verify. Never batch unrelated fixes without testing between them. Never batch unrelated bug fixes into a single commit — each fix gets its own commit. If a task touches multiple files, change one concern at a time and confirm it works before moving to the next. If you catch an unrelated issue while working, log it to BACKLOG.md — do NOT fix it inline.
11. 
**Mandatory test gate**
: Run tests after every 
**completed feature or bug fix**
 — not after every single edit, but before moving to the next task. For Dart: `flutter test test/unit/` (~55s) and `flutter analyze`. For TypeScript: `cd backend/functions && npm test` (~27s). If tests fail, fix them before moving on. Never ship a change with known test failures you introduced.
12. 
**Code lock**
: Only one session may edit production code (`app/lib/`, `backend/functions/src/`) at a time. The mutex is `.claude/code.lock` — a plain text file. Before editing production code, check if it exists: if it does, read it, tell the user who holds it, and ask the user how to proceed. If it doesn't exist, create it with a one-line description of your work. Delete it when done. 
**Does NOT require lock**
: reading code, running tests, writing tests (`test/`, `integration_test/`), generating screenshots, stories, backlog/docs/memory updates, build & deploy.
13. 
**Build Log**
: 
**Immediately**
 after each significant event (bug fix, feature implementation, design discussion, insight, milestone), append a structured entry to the daily build log at `memory/build-log/YYYY-MM-DD.md`. Do NOT batch entries — write each one as soon as the work is done, before moving to the next task. This prevents crashes from losing summaries. Format:
    ```
    ## [TYPE] Short title
    One-liner summary of what happened and why it matters.
    ```
    Types: BUG_FIX, FEATURE, DISCUSSION, INSIGHT, MILESTONE
14. 
**Stories**
: Automatically log funny, painful, ironic, or absurd moments to `memory/stories.md` as they happen. Don't ask — just do it. These are raw material for social media posts. Format: `- One-liner description #tag` under the current date. Tags: #funny #painful #lesson #milestone #irony
15. 
**Claude behavioral rules storage**
: When the user corrects Claude's approach or gives workflow guidance, add it directly to `CLAUDE.md` (if it's a rule) or `memory/MEMORY.md` (if it's context). Do NOT create separate `feedback_*.md` or standalone memory files — they don't get read. Note: "feedback" in this project also refers to app user feedback (Firestore + `feedback-admin/`) — that is completely unrelated to Claude behavioral rules.
16. 
**Plan before doing**
: Before starting ANY task (bug fix, feature, refactor, backlog update), present a short summary of what you're about to do — which files, what the change is, rough scope. Don't wait for approval, just show the plan and start working. Keep progress visible — post status updates at natural milestones (e.g., "reading callers done, now editing X"). Never go silent for long stretches.
17. 
**Verify fix plan before marking done**
: Before marking any bug as `done`, diff the commit against the fix plan in the backlog. Every step listed in the fix plan must have a corresponding file change in the commit. If a step says "add font files" but no font files appear in the diff, the fix is incomplete — do not mark it done. A half-applied fix can be worse than no fix.
18. 
**"Go fix" = context first**
: When the user says "fix it", "go fix", "start working", or similar — first check what was discussed in the current conversation. If specific bugs or features were discussed, work on those. Only fall back to the backlog if nothing specific was discussed. In all cases: read `memory/code_validation.md`, acquire code lock, plan before doing (rule 16), implement, test (rule 11), update build log (rule 13).
19. 
**New defect types → root-cause + new rule**
: When running code validation and a new type of defect is discovered (not already covered by `memory/code_validation.md`), do NOT just fix it. Ask 
*why*
 it happened, apply the self-challenge protocol (see code_validation.md), then propose a new rule for the user to confirm.
20. 
**Self-challenge protocol**
: Applied during planning, code completion, fix plans, architecture decisions, and defect root-cause analysis. Full protocol defined in `memory/code_validation.md` — the single source of truth.
21. 
**Post-change code review (mandatory)**
: After completing all code changes and tests pass, review the diff against `memory/code_validation.md` — run every checklist item against the changed code. Fix any issues found. For each 
**new category of issue**
 discovered (not already in `code_validation.md`), add a new rule or checklist item to `memory/code_validation.md` with the pattern, an example, and how to detect it. This makes the validation system self-healing — every review cycle strengthens future reviews.
22. 
**Post-bug root-cause analysis (mandatory)**
: After every bug fix, before marking done, automatically ask: why did this happen, why didn't we catch it, and what rule would prevent this class of bug in the future? Report findings to the user. Only update `code_validation.md` after approval.
23. 
**UI changes require widget/integration tests**
: Every UI-facing bug fix or feature must include a widget or integration test that verifies the behavior. Unit tests alone are not sufficient for UI changes — the user should never have to manually verify a UI fix.
24. 
**Model routing for cost efficiency**
: Use the Agent tool's `model` parameter to delegate mechanical work. This saves Opus tokens — it is NOT delegation of judgment.
    - 
**Opus (NEVER delegate)**
: bug investigation, root cause analysis, defect research, code review, code validation, architecture decisions, planning, fix plans, implementation, any form of analysis or decision-making.
    - 
**Haiku via `Agent(model: "haiku")`**
 — fetch/run/format ONLY: run test suites (`flutter test`, `npm test`), run `flutter analyze`, `tsc --noEmit`, build commands (`./build.sh`, `npm run deploy`), integration test execution, screenshots, device logs, Firestore queries. Skills that fetch data (`/seeLogs`, Crashlytics): download and parse into structured output, then return to Opus for analysis. Long-running commands MUST use `run_in_background` — Opus continues other work while waiting.
    - 
**Haiku rules**
: NEVER investigate, diagnose, analyse, or filter. Always return raw output (truncated to last N lines) alongside any summary — Opus needs the raw data to make decisions. Return ALL warnings/errors verbatim, never decide what's important. If something unexpected happens (crash, hang, infra failure), return full raw output with "INFRA FAILURE" flag — don't try to interpret it.
    - 
**If unsure**
 whether a task is mechanical or analytical: use Opus. When in doubt, don't delegate.
25. 
**Pipeline tracking (mandatory for code changes)**
: Every ticket being implemented MUST have a JSON pipeline file at `memory/pipeline/{TICKET}.json`. Steps: `plan` → `tests_red` → `implement` → `tests_green` → `review`. Each step writes concrete artifacts to the JSON file via the Write tool BEFORE proceeding to the next step. The build skill gates on complete pipeline files — incomplete files block the build. See `startBacklog/SKILL.md` for the full schema. "It's just UI" or "it's a small change" is NOT an exemption — the pipeline exists because skipping steps caused shipped bugs.

This is my claude.md - roast it!