added what should happen.txt to docs/ which should make code intent easier to understand