update and improve gotchas