Skip to content

For the complete documentation index, see llms.txt.

Example: review inbound documentation PRs

This example teaches Promptless to review documentation PRs that someone other than Promptless opens, such as a contributor or a teammate. Promptless checks each PR for documentation quality and style, and for correctness against your source code. It fixes clear problems directly on the PR branch, comments where the author needs to decide, and submits a GitHub review.

The example follows the process in Teach Promptless a custom task, pairing a written review workflow with a GitHub PR trigger.

  • The GitHub integration connected to your documentation repository, such as acme/docs.
  • An admin role in your Promptless organization, to edit the Knowledge Base and Configuration page. Alternatively, ask Promptless in Slack or Microsoft Teams to make the edits for you.

The workflow tells Promptless how to review a contributor’s documentation PR. It covers when the review applies, what to check, and how to act on what Promptless finds.

  1. In your Agent Knowledge Base, create a workflow file under doc_workflow/. For example, name it doc_workflow/review-inbound-doc-prs.md.

  2. Write the workflow body. Adapt this example to your repository:

    # Inbound documentation PR review
    When a pull request is opened in the docs repo (acme/docs), or someone asks you to review a PR there, and the PR touches documentation content:
    1. Acknowledge the review before starting it. Before doing any review work (reading/verifying the content or making edits), leave a comment on the PR that a review is in progress, so the author and team can see Promptless has picked it up.
    Don't comment on or review out-of-scope PRs.
    2. Review every in-scope PR on the following dimensions:
    - **Quality and style.** Check that the edits match your voice, structure, and formatting conventions, plus any Vale rules the repo enforces.
    - **Correctness against the source code.** Verify the PR's claims against the actual product source, and flag or fix anything stale or unsupported.
    3. Act on your findings.
    - **Make direct edits** on the PR branch for clear fixes, like typos, broken links, wrong flag names, outdated values, awkward sentences with obvious better phrasing, or factual corrections you verified against source. Do not leave a comment asking them to make a change you could make yourself.
    - **Leave comments** when there is ambiguity that needs the contributor to resolve it, like two valid interpretations, a design/intent question, a claim you can't verify from source, or a change that would alter meaning in a way the author should confirm. Comments are for judgment calls, not for changes you're confident about.
    4. Leave a top-level summary comment that states what you reviewed, what you changed directly (with a short list), what you left as open questions/comments and why, and the overall assessment. The summary comment must be present even when you made only direct edits and left no inline comments, and even when you found nothing to change (in which case say so).
    5. Set a GitHub review state. If the docs are correct and ready, approve the PR. Otherwise, submit the review with a Comment state, including when the inline comments from step 3 are still unresolved.
  3. In PROMPTLESS.md, add an “If, then” hook that points to the workflow. Promptless loads PROMPTLESS.md into every run and loads the workflow file only when it needs it, so the hook makes the workflow run reliably:

    If a pull request that touches documentation content is opened in `acme/docs`, then follow the inbound documentation PR review workflow in `doc_workflow/review-inbound-doc-prs.md`.
  4. Select Save on each file. You can also ask Promptless to make these edits, and it commits them for you.

To keep the workflow in your docs repository instead, write it as an Agent Skill in the doc collection, such as .claude/skills/review-inbound-doc-prs/SKILL.md in acme/docs. The PROMPTLESS.md hook then names the doc collection and skill:

If a pull request that touches documentation content is opened in `acme/docs`, then use the `review-inbound-doc-prs` skill from `acme/docs`.

Scope a GitHub PR trigger to your documentation repository so the workflow runs as soon as a contributor opens a PR there.

  1. On the Configuration page, open the Triggers tab.

  2. Select Add an automatic or scheduled trigger, then select GitHub pull requests.

  3. Under Which repositories?, choose your documentation repository, such as acme/docs.

  4. Under When should Promptless run?, select only When it’s opened.

  5. Select Add trigger.

In promptless.yaml, the trigger looks like this:

triggers:
review-inbound-doc-prs:
trigger_type: github_pr
match:
- repos:
- acme/docs
trigger_on:
- opened

When a contributor opens a qualifying PR, Promptless:

  1. Comments on the PR that a review is in progress.
  2. Reads the PR’s title and description, diff, review comments, and commits.
  3. Reviews the changes, editing the PR branch for clear fixes and commenting where the author needs to decide.
  4. Posts a summary comment describing what it reviewed and what it found, and submits a GitHub review state.