I didn’t quite understand why YAML is better than Markdown for such specifications.

If the specification is written in such a strict format as YAML, I would expect it to be executable, something like this https://blog.fooqux.com/blog/executable-specification/

But as far as I understood, for acai that is not the case.

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.

  # 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.

  # 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.

  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.

It's not. And LLMs don't do well with YAML either. I've had the agent/model struggle with `sed` trying to count how many spaces are in there multiple times to get the file to pass. It's the worst format you can use for LLMs.