Skip to content

For the complete documentation index, see llms.txt.

Example: Turn docs analytics into doc-gap suggestions

This example teaches Promptless to turn your documentation-site analytics into prioritized doc-gap suggestions once a week. It follows the process in Teach Promptless a custom task, pairing a written workflow with a schedule trigger. A schedule trigger runs on a repeating clock, with no triggering event.

The workflow reads two signals from PostHog, which measures reader behavior on your docs site:

SignalWhat it tells you
Recurring site-search queries that return zero resultsReaders are looking for a page that’s missing or hard to find.
High traffic combined with a high exit rate on a pageReaders reach the page but leave without their answer.

Adapt the workflow to the analytics tool you use and the signals that matter most to your team.

  • Your PostHog credentials stored as environment variables that Promptless can read. You choose the variable names. This example uses POSTHOG_PROJECT_API_KEY, POSTHOG_PROJECT_ID, and POSTHOG_HOST, which you find in your PostHog project settings.
  • At least one active doc collection.
  • 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 read the analytics and act on them. It covers what to query, which signals matter, how to prioritize, and how much to open.

  1. In your Agent Knowledge Base, create a workflow file under doc_workflow/. For example, name it doc_workflow/analytics-docs-gaps.md.

  2. Write the workflow body. Adapt this example to your analytics tool and docs:

    # Analytics-derived documentation gaps
    When the weekly analytics doc-gaps schedule runs:
    1. Scope every query to your documentation paths only — on-site analytics
    filtered to your docs URL prefix (for example, `promptless.ai/docs`).
    Never pull product analytics.
    2. Read two signals from the last 7 days:
    - **Recurring reader searches with no good answer** (site-search
    queries that return zero results). Each recurring instance is a reader
    asking for a page that does not exist or does not surface. A one-off
    search is noise, not a signal.
    - **Page-level performance** for existing docs pages: traffic and exit
    rate. High traffic combined with a high exit rate points to a page
    readers reach but leave without their answer.
    3. Prioritize what to act on:
    - Propose **new content** for recurring missing results. A reader is
    telling you a page is missing or isn't surfacing, which shows up as a
    zero-result on-site search.
    - For **existing pages**, prioritize by traffic volume combined with how
    recently the underlying feature changed, not by page age. A stable,
    correct old page needs no work.
    4. Redact before publishing. Never paste a raw search-query string or raw
    URL parameters into a suggestion title, description, or PR body — they
    can carry customer names, internal identifiers, or tokens. Describe the
    gap in your own words.
  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 the weekly analytics doc-gaps schedule runs, then follow the workflow in `doc_workflow/analytics-docs-gaps.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 a doc collection, such as .claude/skills/analytics-docs-gaps/SKILL.md in acme/docs. The PROMPTLESS.md hook then names the doc collection and skill:

If the weekly analytics doc-gaps schedule runs, then use the `analytics-docs-gaps` skill from `acme/docs`.
  1. On the Configuration page, open the Triggers tab.

  2. Select Add an automatic or scheduled trigger. Under On a schedule, select A recurring schedule.

  3. Under When should Promptless run?, set a weekly schedule.

  4. Under In which timezone?, choose your timezone.

  5. Under What should Promptless do each time?, enter a short pointer to the workflow file. For example: “Follow the weekly analytics doc-gaps workflow in doc_workflow/analytics-docs-gaps.md.”

  6. Select Add trigger.

In promptless.yaml, the trigger looks like this:

triggers:
analytics-docs-gaps:
trigger_type: schedule
match:
- cron: "0 0 * * 1"
timezone: America/Los_Angeles # optional; defaults to UTC
instructions: |
Follow the weekly analytics doc-gaps workflow in
doc_workflow/analytics-docs-gaps.md.

The cron expression 0 0 * * 1 runs the workflow at midnight every Monday in the trigger’s timezone. Keep instructions a short pointer: the workflow file holds the full job. To pause or adjust the trigger later, edit it on the Triggers tab. For every schedule option, see Schedule triggers.

When the weekly schedule runs, Promptless:

  1. Pulls the last 7 days of documentation-site analytics from PostHog, scoped to your docs paths.
  2. Applies both signals and the workflow’s prioritization.
  3. Opens suggestions, describing each gap in its own words with no raw queries or URL parameters.
  4. Finishes without a suggestion when it finds nothing worth changing.

A scheduled run shows its results only through the suggestions it opens and the notifications your policies send. Set a notification channel to see what each run produced. A quiet week means the run found nothing worth changing. A credential or access problem sends an escalation notification, not a suggestion notification. Set an escalation channel to catch a broken integration.