cleaned up the specs

Did a gentle first pass on the specs:
- cleaned up whitespace
- fixed missing newlines
- fixed missing spaces
- separated logical blocks
- added a few before blocks
- edited a few things for improved clarity