Seiso: Markdown Convention and Linter for AI-Generated Docs

What changed

Seiso, a fresh release from scarletkc, introduces a structured Markdown convention and a linter to address challenges in managing project documentation, particularly when generated by AI. The tool is built in Rust and is available via Cargo, PyPI, and npm packages, with prebuilt binaries for common platforms like macOS, Linux (x64 and arm64), and Windows x64. For other platforms, including musl-based Linux, installation via Cargo is recommended, or the PyPI package can build from source with a Rust toolchain.

The core of Seiso is its convention, which dictates how Markdown files should be organized. Key principles include:

• Single Kind Declaration: Each document should declare a single kind (e.g., howto, reference, adr) and contain only content relevant to that kind.
• Single Source of Truth: Facts should reside in one primary location, with other pages linking to it rather than duplicating information.
• Separation of Volatile Data: Information that changes frequently, such as version numbers or deployment status, should not be hardcoded into long-lived pages.
• Clear Pointers: Sentences should use pointers to refer to files or symbols, guiding readers directly to the promised information.
• Objective Prose: Documentation should avoid addressing the reader directly or narrating its creation process.
• Documented Judgment Calls: Decisions that tools cannot automate should be written down with a clear reason.

The seiso command-line tool facilitates this convention. seiso init generates a seiso.toml configuration file, suggesting exclusions, kind mappings, and documentation site entries for review. seiso check runs stable rules by default, ensuring adherence to established conventions. Experimental rules are available in preview mode using the --preview flag, which should be tested locally before integration into CI pipelines.

Why it matters for builders

As AI increasingly assists in generating project documentation, maintaining its accuracy and consistency becomes critical. Seiso provides a framework to standardize this documentation, making it more reliable for both human developers and AI coding agents. By enforcing a clear structure and identifying inconsistencies, Seiso helps prevent the spread of misinformation that can arise from unmanaged, AI-generated content, thereby improving the overall quality of project knowledge bases.

Practical impact

AI builders can integrate Seiso into their development workflows to automate documentation checks. The tool's diagnostics provide specific locations and suggested fixes, enabling AI agents to potentially repair documentation issues autonomously. Developers can start by running seiso init in their repositories to set up a basic configuration and then use seiso check to identify any convention violations. Exploring the preview rules with seiso rule --all and seiso rule <rule_name> can help identify areas for further improvement and potential automation.

Caveats and source limits

The source indicates that Seiso is a fresh release with version v0.2.0. While it offers stable and preview rules, the preview rules are experimental and may produce false positives. The effectiveness of AI agents in repairing findings from seiso's output is described as potential, rather than a guaranteed outcome. The documentation does not provide independent benchmark results for the linter's performance or specific metrics on how it improves documentation quality or agent performance. Pricing information is not available as it is an open-source project. The source also mentions integrations with Claude Code hooks and pre-commit, but detailed implementation guides for these are not elaborated upon in the provided excerpt.