Refactor base_spec to read clearly, add documentation

This commit refactors the `base_spec` file to read more clearly and to tell a clearer story of what `roles_on_routes` is doing.

by Steve & Nick