Why I Built an AsciiDoc Traceability Extension (And What AI Had to Do With It)

Why Another Traceability Tool?

I work at a Biotech company. Our mission is to advance scientific understanding and medicine by providing solutions for cell and gene therapy and biomedical research. For this, we also produce instruments for research and for cell therapy. Parts of this require full traceability for compliance reasons. For this, we currently use a tool called Polarion. Polarion works for most development, but developers in the software group resist it. Problems we encounter:

  • Developers document already in our repository using Markdown.

  • They are using plantuml as a diagramming tool.

  • Generating diagrams and manually keeping them in sync with Polarion means diagrams quickly fall out of date.

  • The structure in Polarion is quite rigid. People try to write the bare minimum.

We want to bring the documentation that design control requires — with traceability — closer to where people work: in the code. But for this, we need support for traceability.

The first idea was creating a link to Polarion and syncing texts back. This was a small side project I was working on using Antora.

Sphinx-Needs Showed It’s Possible

Then a colleague made the jump: What if we could get rid of Polarion completely? But this would require supporting traceability in the documents. A part of our software was already using Sphinx to provide richer documentation than using Doxygen. That was the starting point. He soon discovered that Sphinx Needs supports traceability. He showed the proof-of-concept before I went on vacation. I am fine with any text-based tool, but I still prefer AsciiDoc for technical documentation more than reStructuredText or Markdown.

Spec-Driven Development Meets AI

I also wanted to use the project to explore more spec-driven development using frameworks like OpenSpec or BMad.

For this project, I settled with OpenSpec. Every change I made was first explored, proposed, applied, archived and synced. A little later, I created a skill to sync specs with the example site. From platforms used, I went from Claud over Mistral to DeepSeek. DeepSeek was ok for this kind of project because it is open source and published on GitHub anyway. So, they will eventually use it for their model training. DeepSeek had the benefit that it costs a magnitude less than the other platforms. Unfortunately, this time is over. This week, they announced a significant price increase. Hope, I am able to still conduct one experiment: Giving the LLM the example site and see, if a working version can be built. This would give me good ideas, what needs to be better documented. Requirements are also a bit technical. Normally, you would not get requirements on that level.

How did it go?

I found the workflow quite good. The only issue is, when you had applied the proposal, and you did some manual testing and detected some errors, it turned quickly into vibe coding. You had to remind the LLM to write a spec or proposal for what had been changed. A few times, I asked the LLM to take the role of a senior developer and review the code base and make some improvements.

What’s the difference:

Not sure if there are conceptually real differences. We made the choice that it would be a good idea to delegate some of the more complex queries to Neo4j (at least for now). The main purpose should be on establishing the traceability links. However, you often collaborate on these kinds of documents using comments; we added the annotate.js library to the default ui theme. But this requires export and import, and we need to improve in this area. But this is probably not something that belongs to the core product.

What’s Next

  • Get community feedback.

  • Run experiments to re-create the project using its own requirements

  • Add some more features found in Sphinx needs, that would make sense to have them in antora-tracer as well

  • Some general enhancements

    • Overview page generation for issues, like:

      • invalid links between items (using undefined links types for this combination)

      • orphaned items (no in- or outgoing links)

  • Allowing more attributes on items and report generation

  • support creating reporting on role types / prefix etc.

Tell me what you would like to have included.