Lint AI-Written Project Documentation with seiso

What seiso does

seiso is a Markdown convention and linter for project documentation written by AI and read by people and coding agents. It helps repositories keep documentation consistent, maintainable, and easier to use as context for future changes.

The tool checks documents against a shared convention rather than requiring every project to invent its own documentation rules. Each document declares a kind, such as howto, reference, or adr, and contains only the material appropriate for that kind.

seiso also encourages each fact to have one authoritative home. Other pages should link to that source instead of repeating the same information. This reduces contradictions, especially when AI-generated documentation copies a field list, version, status, or count into several files.

Core documentation principles

• Every document declares one kind and follows that kind's purpose. A how-to explains steps, while design reasoning belongs in an ADR.
• Each fact has one home. Other documents link to the authoritative page instead of restating it.
• Long-lived pages avoid values that change faster than the page, including versions, deployment status, and counts.
• A pointer identifies a file or symbol when a sentence refers to a concrete implementation detail.
• Finished documentation should not address the person who requested it or narrate how the document was produced.
• Judgment calls that a tool cannot make should be recorded with a reason. An unexplained exception is itself a violation.

seiso focuses on these documentation rules. It does not try to determine whether prose sounds machine-written, and it leaves formatting and spelling to other tools.

Install seiso

Choose one of the supported installation methods. The Rust, Python, and npm packages provide the same command-line tool.

cargo install seiso

uv tool install seiso
# Or use pipx:
pipx install seiso

npm install -g @scarletkc/seiso

The PyPI and npm packages include prebuilt binaries for macOS on Apple silicon and Intel, Linux x64 and arm64 with glibc, and Windows x64. On other platforms, including musl-based Linux distributions such as Alpine, install with Cargo. The PyPI package can also build from source on those platforms, provided that a Rust toolchain is available.

If you are working from a source checkout, run commands through Cargo:

cargo run -- <command>

Initialize a repository

Run seiso from the repository root. Start by asking it to create an initial configuration:

seiso init

This writes a seiso.toml file at the repository root. The generated configuration includes suggested exclusions and document-kind mappings. Review those suggestions before relying on the results, because the initial mapping is a starting point for your repository rather than a substitute for project decisions.

Run the first check

After reviewing the generated configuration, check the repository:

seiso check

By default, seiso check runs only stable rules. These rules have met seiso's promotion criteria and are intended to provide the dependable baseline for a project.

Diagnostics identify where a problem occurs and explain how to fix it. Many findings can therefore be repaired directly from the command's output. When a finding requires human judgment, such as deciding which of two pages should own a fact, the diagnostic names the decision that needs to be made.

Explore rules and document structure

Use the rule commands to understand what seiso can check:

seiso rule --all
seiso rule <CODE>

seiso rule --all lists every rule and shows its status. Use seiso rule <CODE> to view an individual rule with examples.

To inspect seiso's document model without running the rules, use:

seiso parse

This is useful when you are learning how the tool interprets a document or investigating why a check produced a particular result.

Use preview rules carefully

Rules that have not yet met the promotion criteria are available as previews. Preview rules are experimental and may report false positives, so they are not enabled by the standard check.

Try them locally with the --preview option:

seiso check --preview

Preview rules are useful for finding potential documentation issues early, but the README recommends keeping them out of CI gates until they become stable. A practical workflow is to use stable rules for required checks and preview rules for optional local review.

Adopt seiso in a documentation workflow

1. Install seiso using Cargo, uv, pipx, or npm.
2. Run seiso init from the repository root.
3. Review the suggested exclusions and kind mappings in seiso.toml.
4. Run seiso check and resolve the reported findings.
5. Use seiso rule --all and individual rule explanations when you need to understand a diagnostic.
6. Experiment with seiso check --preview locally, but avoid using preview findings as CI gates.

For larger workflows, seiso's documentation includes guidance for configuration, rule selection, and output formats, as well as Claude Code hooks, pre-commit, and CI integrations.

Advanced guidance

Keep facts authoritative

When seiso reports duplicated or misplaced information, decide which document should own the fact. Move the canonical explanation there and link to it from related pages. This makes updates safer and gives both readers and agents a clear source of truth.

Match document kinds to intent

Use a howto for procedural steps, a reference for durable factual information, and an adr for the reasoning behind a design choice. Keeping these purposes separate prevents a page from becoming a mixture of instructions, reference data, and historical decision-making.

Record justified exceptions

Some repository decisions require judgment rather than a mechanical rule. When you keep an exception, document the reason. seiso treats an exception without an explanation as a documentation problem because future contributors and agents cannot tell whether it was intentional.

Consult the convention when a rule is unclear

The seiso convention defines each document kind's contract and the evidence a diagnostic can claim. Use it alongside the output of seiso rule <CODE> when you need to understand the expected structure or decide how to repair a finding.

Conclusion

seiso gives project documentation a shared structure and a focused validation tool. Install it, generate and review seiso.toml, run stable checks, and use rule explanations to make documentation easier for humans and coding agents to trust. Treat preview rules as experimental until they are promoted, and keep decisions about ownership and exceptions explicit in the repository.