Skip to content

For the complete documentation index, see llms.txt.

Promptless Promptless | Automatic updates for your customer-facing docs
Get a demo Start for free

Doc Detective Integration

Docs describe how your product works. Every setup guide, UI walkthrough, CLI example, and API tutorial contains product assertions: this button exists, this command succeeds, this page appears, this link works.

Promptless uses Doc Detective to make each of those assertions executable. Doc Detective is an open-source implementation of the Docs as Tests framework: documentation should be tested against the real product experience, not just proofread for style or checked for broken links.

Doc Detective is an open source documentation testing framework. You can view the core project at doc-detective/doc-detective and the agent tooling Promptless uses at doc-detective/agent-tools.

What Promptless does

Section titled “What Promptless does”

When Doc Detective is enabled on a doc collection, Promptless treats tests as part of keeping your docs current.

Promptless can:

  • Create Doc Detective tests when new documented workflows, UI paths, commands, or setup procedures are added
  • Update existing Doc Detective tests when product changes make the old workflow stale
  • Reuse your existing Doc Detective config and test layout instead of inventing a separate structure
  • React to CI failures on Promptless documentation PRs, inspect the failing checks, and update the suggestion branch when the failure is caused by the docs change

This means Promptless can update both the prose and the executable test coverage for a feature. If a new feature changes the product, Promptless can document the change and add the checks that prove the documented workflow still works.

Setup

Section titled “Setup”

Enable Doc Detective from your doc collection settings.

  1. Open the Promptless dashboard.
  2. Go to your doc collection.
  3. Click the edit button.
  4. Enable Doc Detective.
  5. Optionally enter the repo-relative path to your Doc Detective config file, such as .doc-detective.json, .doc-detective.yaml, or .doc-detective.yml.

If you leave the config path empty, Promptless still knows Doc Detective is enabled and will inspect the repository for existing Doc Detective specs and config files before adding coverage.

CI failure handling

Section titled “CI failure handling”

Doc Detective is most useful when it runs in CI with the rest of your documentation checks.

When a GitHub check suite fails on an open Promptless docs PR, Promptless:

  1. Resolves the failing PR back to the Promptless suggestion that created it.
  2. Fetches the failing check runs and a preview of the logs.
  3. Starts a follow-on investigation with the PR, failing check names, conclusions, and log preview.
  4. Determines whether the failure was caused by the suggestion.

If the failure is caused by the suggestion, Promptless updates the suggestion branch with the fix. If the failure is pre-existing or unrelated, Promptless leaves the suggestion scoped to its original work. If it finds a separate docs issue outside the suggestion’s scope, it can create separate work for that issue instead of expanding the original PR.

This lets Doc Detective failures become actionable maintenance signals instead of another queue for your team to triage manually.