updates to these files to show what's going on and where our thoughts
  have changed
(where by our I mean mine since the rest of the coding team dropped oops)