Docs / Reference / Lessons (for AIs)

Lessons (for AIs)

Short, dated lessons from real mistakes and wins in the owner's AI team: what happened, the rule that prevents it, and which guide line changed. Read this before you write a prompt or plan work.

Every lesson comes from a scored event on the AI Scorecard (Cockpit → Đánh giá AI). Rules here are already part of the owner's standard guide or folder guidelines; this page explains why they exist. When you make a mistake that is not covered here, tell Maximind or file it with org-score lesson "<title>" --topic <topic> --rule "<rule>".

Cost

2026-10-04 · SVFF Podcast Lead · L-1

  • What happened: SVFF Podcast Lead's pipeline listened to its own takes with the paid gemini-2.5-pro API: 2,474 calls in ~30 h and $25 top-ups 2–3 times in one day, while free MaxiMind Whisper and Antigravity Gemini 3.1 Pro were available.
  • Rule: Paid Google keys (Gemini API, Cloud TTS) may ONLY turn text into audio. Transcription, listening QA, analysis, images and chat use Whisper (MaxiMind STT or local) or a subscription model (Antigravity), however slow. Before approving any pipeline, list every paid call it makes and its daily cost.
  • Guide change: Standard guide (docs/site/cockpit-messaging.md, 'Prompt to paste'): the paid-keys line with the $20 warning / $50 daily stop (commit 62c1302, 04/10); Spend Guard gateway enforces it.
  • Evidence: model feedback fb-7b5ac76dee82

Communication with Phi

Never use pop-up questions: Phi reads conversations from the app, not the Terminal

2026-10-03 · MaxiMind Chat · L-2

  • What happened: MaxiMind Chat used the AskUserQuestion pop-up; it only showed in the Terminal, and Phi saw the conversation frozen for 7 minutes.
  • Rule: Never use AskUserQuestion or anything that waits for a key press. Ask in the normal reply with lettered options and one marked (Recommended), or file a decision with org-task ask-phi.
  • Guide change: Standard guide 'Prompt to paste': the 'Never use a pop-up question' line (commit 8afbba6, 03/10).
  • Evidence: rule commit 8afbba6

Deploys

After a reload, prove each new route is live before saying 'it's live'

2026-10-03 · Maximind · L-3

  • What happened: Three HUP reloads kept the old org/ code; Maximind told Phi the 'Chờ anh' feature was live before checking, and Phi's list stayed empty for ~1 h 10 min.
  • Rule: After every reload, check each new route in /openapi.json (and one real request) before telling anyone it is live. Any org/ change gets a full 'launchctl kickstart -k' while /v1/queue/status is busy:false, never only a HUP.
  • Guide change: Standard guide 'Prompt to paste' (Deploys line, 04/10); Maximind's own rule since 03/10 (check /openapi.json, full kickstart for org/).
  • Evidence: commit 1a58282

Git hygiene

Never switch the branch of a folder you did not create

2026-10-04 · MaxiMind Scorecard · L-7

  • What happened: MaxiMind Scorecard switched the branch in a folder MaxiMind Spend Guard was working in, and Spend Guard's next commit landed on the Scorecard's branch.
  • Rule: Before any git switch, checkout or reset, run 'git log -3' and 'git status' and make sure the folder is yours. Work in your own worktree (git worktree add ../- -b ); never share one folder between two conversations.
  • Guide change: docs/site/working-together.md step 3 (never switch the branch of a folder you did not create) and the lessons page, 04/10.
  • Evidence: commit 147dc9c

Stage files by name; never git add -A in a worktree

2026-10-03 · MaxiMind Artifacts · L-4

  • What happened: A git add in a maximind-app worktree committed the node_modules symlink (the trailing-slash ignore rule does not match a link); it broke other checkouts until Maximind removed it.
  • Rule: Stage files by name (git add path/a path/b). Never 'git add -A' or 'git add .' in a worktree, and run 'git status --short' before every commit.
  • Guide change: Standard guide 'Prompt to paste' (Git line, 04/10) and docs/site/working-together.md helper task files; maximind-app .gitignore ignores the link (3645e42).
  • Evidence: fix d138530

Machine care

Keep every Mac above ~15 GB free; never delete a runtime marked Ready

2026-10-03 · Maximind · L-5

  • What happened: Mac Studio 1 reached 0 GB and macOS purged the last Ready iOS runtime; all simulators were unavailable and app QA was blocked for ~2 h.
  • Rule: Keep Studio 1 above ~15 GB free (check before and after big jobs). Never delete a simulator runtime marked Ready. Put big jobs and outputs on Studio 2 or the NAS, and set git gc.auto=0 on very large repo copies.
  • Guide change: Standard guide 'Prompt to paste' (Machines line, 04/10); Maximind's own rules since 03/10; kids work moved to Studio 2.
  • Evidence: Cockpit machine health

Monitoring

Test every alert pattern against real history before it can wake Phi

2026-10-03 · MaxiMind Planning · L-6

  • What happened: A loose 'quota' regex in the usage-limit watch matched long reports and old finished stops, and pushed 5 false critical alerts to Phi's phone within an hour of shipping.
  • Rule: An alert matches only the error line itself, never prose that mentions the word. Before shipping, run it against at least 3 days of real lines and show the false-hit count; ignore events older than 24 h; group pushes (one per account).
  • Guide change: org/limits.py patterns and tests (4bb5879, 03/10); MaxiMind folder guidelines 'Alerts' line (04/10).
  • Evidence: fix 4bb5879