retro #83: LEARNINGS.md — agent-add checklist, prompt-heredoc discipline, one-round bounce

Distilled from issue #83 / PR #84 (adding @intern):
- missed agent.yml trigger gate (broke all @intern comments until round 3)
- 2 of 8 touched files missed on first pass
- stray leading-space edits to run-agent.sh prompt heredoc bounced 2 rounds
- @qa quoted the fix-attempt trigger string, inflating bounce counter 1/3 -> 3/3
- @qa split whitespace + gate findings across rounds, hitting the 3-round cap

LEARNINGS.md

@@ -0,0 +1,9 @@
+# LEARNINGS — distilled from retros
+
+Rules for the team. Each line: `symptom -> rule for next time`. Keep concrete and checkable.
+
+- New agent added without the `agent.yml` trigger gate, breaking all `@intern` comments until round 3 -> adding an agent means editing BOTH the trusted-author list and the mention list in `agent.yml` (lines ~28 and ~37) in the same commit; @qa grep the gate for the new name.
+- Two of the 8 files an agent touches were missed on the first PR -> when adding an agent, touch all of `agents.json`, `install-opencode.sh`, `route.sh`, `agent.yml`, `publish.sh`, `rescue-pr.sh`, `run-agent.sh`, `README.md`; @qa diff-stat the PR and confirm the name appears in each.
+- Stray leading-space edits to `run-agent.sh` prompt heredoc bounced 2 review rounds -> only edit the exact token (the agent name) inside prompt heredocs, never re-indent surrounding lines; verify with `cat -A` against `main` before pushing.
+- @qa quoted the `@${dev} ... (fix attempt $n/3)` trigger string from the diff, inflating the bounce counter 1/3 -> 3/3 -> @qa paraphrase the fix-attempt line, never reproduce it verbatim; the publish.sh template+regex must stay pinned together.
+- @qa found whitespace and the gate miss in separate rounds, hitting the 3-round cap -> on a BOUNCE, list ALL problems (every file/line) in one round; the 3-round cap is hard.