src/graphics/display/drivers/virtio-gpu-display/docs/spec-processing.md

# Processing the virtio specification for AI agents

Our experiments show that AI agents working on this driver benefit from having
access to a Markdown version of the virtio specification, broken down into
subsections.

Our experiments also show that the prompt below consistently works with fronteer
models. The prompt assumes that [Python](https://www.python.org/) and
[Pandoc](https://pandoc.org/) are installed on the local machine.

```
## Goal

Obtain a copy of the virtio specification optimized for consumption by AI
agents.

## Source

The latest virtio specification is at
https://docs.oasis-open.org/virtio/virtio/v1.4/virtio-v1.4.html

## Process

Follow the steps below to obtain a cleaned up specification.

1. Create a `local/virtio-spec/` directory, if it does not already exist.

2. Download the source specification to the `local/virtio-spec/` directory, as
   `all.html`.

3. Use the `pandoc` invocation pattern below to convert the specification to
   Markdown, and save it as `local/virtio-spec/all.md`.

    ```bash
    pandoc --from=html --to=markdown-smart --wrap=auto --markdown-headings=atx \
        --columns=80 all.html -o all.md
    ```

4. Read the specification's table of contents, which is roughly at the beginning
   of the file.

5. Write a shell command or Python script that extracts the table of contents to
   `local/virtio-spec/toc.md`.

   * Validation: Run the script and read the output file.
   * Iteration: If necessary, fix the script and iterate.

6. Write a shell command or Python script that extracts each top-level section
   to `local/virtio-spec/section{section_number_or_letter}.md`.

   * Example: section 3 goes to `local/virtio-spec/section3.md`.
   * Validation: run the script and read the first, second, next-to-last and
     last output file.
   * Iteration: If necessary, fix the script and iterate.

7. Write a shell command or Python script that extracts each transport subsection
   to `local/virtio-spec/transport-{transport_type}-section{section_and_subsection}.md`.

   * Examples: `local/virtio-spec/transport-pci-section4_1.md`,
     `local/virtio-spec/transport-mmio-section4_2.md`.
   * Validation: run the script and read the first, second, next-to-last and
     last output file.
   * Iteration: If necessary, fix the script and iterate.

8. Write a shell command or Python script that extracts each device subsection
   to `local/virtio-spec/{device_type}-section{section_and_subsection}.md`.

   * Examples: `local/virtio-spec/net-section5_1.md`,
     `local/virtio-spec/block-section5_2.md`.
   * Validation: run the script and read the first, second, next-to-last and
     last output file.
   * Iteration: If necessary, fix the script and iterate.

9. Write a summary of the directory's contents in
   `local/virtio-spec/overview.md`. Your primary audience is AI agents.
```