Skip to content

Explicitly include DITA validation in docs-writer.md agent instructions #86

@GabiNecasova

Description

@GabiNecasova

Description

While reviewing the documentation workflow in this repository, I noticed a slight disconnect between our available tools and the instructions provided to the docs-writer agent.

Current State:

  • DITA rules are already configured in .vale.ini.
  • There is a dedicated skill available: dita-validate-asciidoc.
  • However, the docs-writer.md agent instructions mention running vale generally but do not specifically reference the DITA validation script or the necessity of DITA-safe conversion.

Proposed Change:

I suggest updating docs-tools/agents/docs-writer.md to explicitly include a DITA validation step. This ensures the agent is aware that content must be successfully convertible to DITA format and knows which script to run to verify this.

Proposed Content Addition:

## DITA validation
Run the DITA validation skill to check for DITA conversion issues:

bash dita-tools/skills/dita-validate-asciidoc/scripts/validate_asciidoc.sh /path/to/file.adoc

This validates against the AsciiDocDITA rules from https://github.com/jhradilek/asciidoctor-dita-vale to ensure the content can be successfully converted to DITA format. Fix all ERROR-level issues before saving.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions