# Automatic documentation review on pull requests

import { Aside } from '@astrojs/starlight/components';

<Aside type="note" title="Beta">
  Docs Agent is in beta. Contact support@ekline.io to request access.
</Aside>

When you open a pull request, EkLine automatically analyzes the changes and determines whether your documentation needs updating. Depending on the confidence of the assessment, EkLine stays silent, posts a suggestion, or triggers a documentation update automatically.

## How it works

```mermaid
flowchart TD
    A[Pull request opened] --> B[EkLine analyzes PR diff]
    B --> C{Documentation impact?}
    C -->|Low confidence| D[No action taken]
    C -->|Medium confidence| E[Posts suggestion comment]
    C -->|High confidence| F[Posts auto-trigger comment]
    F --> G[Docs update flow runs automatically]
    G --> H[Documentation PR created]
    E --> I[You decide whether to trigger]
```

When a non-draft pull request is opened or converted from draft to ready, EkLine:

1. Reads the PR diff, title, and description.
2. Compares the changes against your existing documentation.
3. Assesses whether the changes have documentation impact.
4. Acts based on the confidence of that assessment.

<Aside type="note">
EkLine runs the assessment once per pull request. New commits pushed to the same PR do not trigger a re-analysis.
</Aside>

## Confidence tiers

EkLine categorizes each assessment into one of three confidence tiers:

| Tier | When it applies | What EkLine does |
|------|-----------------|------------------|
| **Low** | Refactoring, test additions, bug fixes with no user-facing impact | Stays silent — no comment posted |
| **Medium** | Behavioral changes that might affect documented features | Posts a suggestion comment on the PR |
| **High** | New API endpoints, renamed configuration, removed features, changed public interfaces | Posts a comment that automatically triggers the docs update flow |

The high-confidence threshold is conservative. EkLine only auto-triggers a documentation update when the impact is clear. When uncertain, it defaults to staying silent.

### Medium confidence

EkLine posts a comment on the pull request explaining what documentation might need updating. The comment mentions `@ekline-ai` so you can trigger the update manually if you agree.

No automatic action is taken — you decide whether to proceed.

### High confidence

EkLine posts a comment that automatically triggers the [GitHub PR bot](/agent/github-integration/) flow. The bot creates a documentation session, generates a draft, and opens a docs pull request — without any manual intervention.

This works the same way as manually mentioning `@ekline-ai` on a PR comment, except EkLine initiates it for you.

## Prerequisites

Before automatic PR review works on your repositories, you need:

- An EkLine organization account.
- The [EkLine GitHub App](https://ekline.io/settings) installed on the repository.
- Docs Agent access enabled for your organization (includes the GitHub PR bot integration).

Automatic PR review is enabled by default for all organizations with Docs Agent access.

## What you see on the pull request

| Scenario | What appears on the PR |
|----------|------------------------|
| Low confidence | Nothing — EkLine stays silent |
| Medium confidence | A comment suggesting a documentation update, with `@ekline-ai` mentioned for convenience |
| High confidence | A comment that triggers the docs update flow, followed by a link to the documentation PR |
| Error during assessment | Nothing — EkLine stays silent and logs the error internally |

At most one automatic review comment appears per pull request.

## Relationship to the GitHub PR bot

Automatic PR review builds on top of the existing [GitHub PR bot](/agent/github-integration/) integration:

- **Manual flow**: You mention `@ekline-ai` in a PR comment to trigger a documentation session.
- **Automatic flow**: EkLine posts the `@ekline-ai` mention for you when it detects high-confidence documentation impact.

Both flows create the same type of documentation session. If EkLine already posted an automatic comment and you mention `@ekline-ai` manually on the same PR, the existing session resumes rather than creating a duplicate.

## Run a manual assessment

You can also trigger a PR documentation assessment on demand using the `/analyze-pr-for-docs-needs` command in the EkLine Docs Agent. Provide the PR URL as an argument:

```text
/analyze-pr-for-docs-needs https://github.com/your-org/your-repo/pull/123
```

The agent analyzes the PR diff against your existing documentation and acts based on the same confidence model described above. Use this when you want to assess a specific PR without waiting for the automatic trigger, or to re-assess a PR after significant changes.

## Current limitations

- **Assessment runs once**: New commits pushed after the initial assessment do not trigger a re-analysis.
- **No user configuration**: You cannot customize confidence thresholds or trigger conditions. This is planned for a future release.
- **PR context only**: The assessment uses the PR diff, title, and description. Linked Jira or Linear tickets are not included.
- **Current PR changes only**: EkLine assesses documentation impact for changes introduced by the PR, not pre-existing documentation gaps.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| No comment appears on my PR | Verify the EkLine GitHub App is installed and Docs Agent access is enabled for your organization. Draft PRs are skipped. Low-confidence assessments produce no comment. |
| EkLine posted a suggestion but I want the update | Mention `@ekline-ai` in a new comment on the PR with a description of the documentation changes you need. |
| The auto-triggered docs PR is inaccurate | Comment on the generated docs PR mentioning `@ekline-ai` with feedback. The agent resumes the session and pushes new commits. |
| EkLine triggered on a PR that does not need docs | The assessment is best-effort. You can close or ignore the generated docs PR. |

## Next steps

- [GitHub PR bot](/agent/github-integration/) — Trigger documentation sessions manually from PR comments.
- [Create documentation](/agent/create/) — Generate documentation from your codebase, videos, and external sources.
- [Update and review](/agent/update-review/) — Keep documentation in sync with code changes.