Comment by brendanmc6

Here is how I got from Markdown to YAML in a few easy steps:

1. Start with unmaintainable prompt.

  Add auth to the admin route. It must only be accessible to team members. It must not be accessible to team members with the `quarantine` role. Unauthorized users should be redirected to the /login page, with query param `?error=unauthorized`. Requires fresh session, no older than 10 minutes.

2. Put it in a structured .md spec of some kind

  # Feat: Admin Route

  ## Auth requirements

  * [ ] Accessible to team members.
  * [ ] Not be accessible to members with `quarantine` role.
  * [ ] Redirects unauthorized users to /login
    * [ ] Redirect path includes `?error=unauthorized`
  * [ ] Requires fresh session, no older than 10 minutes.

But how do you cross reference the requirements? Give them stable IDs?

  # Feat: Admin Route

  ## Requirements

  AUTH.1: Accessible to team members.
  AUTH.2: Not be accessible to members with `quarantine` role.
  AUTH.3: Redirects unauthorized users to /login.
    AUTH.3.1: Redirect path includes `?error=unauthorized`.
  AUTH.4: Requires fresh session, no older than 10 minutes.

Might as well clean it up and make it machine readable at that point?

  feature:
    name: admin-route

  requirements:
    AUTH:
      1: Accessible to team members.
      2: Not be accessible to members with `quarantine` role.
      3: Redirects unauthorized users to /login.
      3-1: Redirect path includes `?error=unauthorized`.
      4: Requires fresh session, no older than 10 minutes.

```