Skip to content

For the complete documentation index, see llms.txt.

Shape how Promptless communicates with your team

Promptless messages your team throughout its work. It confirms each request and announces each suggestion. When it’s blocked, it asks for what it needs. On the pull requests that started the work, it leaves a summary. Those messages are how your team decides what to review and what to fix. Shape them to fit how your team works, so the right people see them and act on them.

You steer Promptless’s messages with three files in your Agent Knowledge Base:

  • The policies in promptless.yaml choose the channels for suggestion notifications and escalations, and turn pull request comments on or off.
  • doc_workflow/notification_preferences.md sets when Promptless notifies, whom it mentions, and how its messages read.
  • PROMPTLESS.md adds messages for other events, such as a reply in a Slack thread when a suggestion’s docs PR merges.

Start from the message you want to change. Each one has its own destination and its own lever:

MessageWhen Promptless sends itWhere it goesSteer it with
Progress updateSomeone asks Promptless for work in a Slack or Teams thread, or on a dashboard taskThat thread or task. A short acknowledgement comes first, then one line for each milestone that changes what you know.Tone and mention rules in the preferences file
Suggestion notificationA suggestion is ready for review, or Promptless updates itThe thread the request came from, or the notification channel in your policies. An MCP submitter gets a Slack direct message.Notification policies, and the preferences file for timing, format, and tone
EscalationPromptless is blocked on something only your team can fix, or notices something worth a lookThe thread the request came from, or the escalation channel or email address in your policiesEscalation policies
Source PR summaryA GitHub PR or GitLab MR trigger produces a suggestionA comment on that PR or MR that links each documentation suggestionpublishing.suppress_source_pr_comments
Docs PR descriptionPromptless opens a documentation PRThe PR body, with the suggestion’s description, an “Open in Promptless” link, and the trigger events that led to the changepublishing.suppress_pr_description_extras, and instructions in PROMPTLESS.md

Progress updates go only to a thread where someone asked Promptless for the work or Promptless already posted. Notification channels receive suggestion notifications and escalations.

Set notification and escalation channels in the policies section on the Configuration page. A rule can send one doc collection’s messages somewhere else:

policies:
default:
notification:
slack_channel: docs-updates
escalation:
slack_channel: docs-escalations
email:
- docs-team@example.com
rules:
- if:
doc_collection: acme/api-docs
then:
notification:
slack_channel: api-docs-review

Here, suggestions for acme/api-docs go to api-docs-review, and every other suggestion goes to docs-updates. Problem reports for every collection go to docs-escalations and the team’s email address.

Keep escalations in their own channel when your notification channel is busy, so a blocker doesn’t scroll past unseen. To turn off an inherited channel, route to Microsoft Teams, or see when a problem report falls back to the notification channel, see Customize notifications.

To keep Promptless off source pull requests, set publishing.suppress_source_pr_comments: true. Teams often do this during a pilot, before Promptless is introduced to the wider engineering team. See Suppress source PR comments.

Write your preferences in plain language in doc_workflow/notification_preferences.md. Promptless reads the file each time it writes a message. Anything you leave out keeps the default behavior.

  1. In the Promptless dashboard, open Settings and select Agent Knowledge Base.

  2. Open doc_workflow/notification_preferences.md.

  3. Add your preferences. Use the examples below as a starting point.

  4. Select Save.

Promptless applies the preferences from its next message on.

What you want to changeExample instruction
ToneDon't thank or praise the person you credit. State plainly where the change came from.
Whom Promptless mentionsIn Slack notifications, @-mention the person who requested the change. Name reviewers in plain text.
How links lookWrite every link as link text, never as a bare URL.
When Promptless notifiesSkip notifications for suggestions that only fix typos.
Suggestion cardsLeave the suggestion preview card off notifications in #docs-firehose.
Message formatFormat suggestion notifications as: What changed, Review link, Docs PR link.

By default, Promptless mentions at most one person in a message. It names everyone else in plain text, so crediting or assigning someone doesn’t ping them. A mention rule you write replaces that limit and applies to every message Promptless sends.

A format you state replaces the default suggestion notification format completely: Promptless posts the fields you list, in your order, and nothing else. Escalations keep their own format, because a blocker always ends with what Promptless needs from you and what happens next. For the default format and a full custom format, see Notification preferences file.

To decide who reviews and owns the work, rather than how messages read, see Route and assign suggestions to the right people.

To have Promptless post when something else happens, add an “If, then” instruction to PROMPTLESS.md. Promptless reads that file at the start of every session, the same way it picks up the hooks that activate custom tasks.

For example, to close the loop with the people who asked for a change:

If a suggestion's docs PR merges or closes, or a suggestion is closed or archived,
then reply in the Slack thread where you announced that suggestion. Say how it
resolved and link the docs PR.

PROMPTLESS.md also shapes the docs PRs Promptless opens. For example, to show reviewers whom to follow up with:

When a docs PR comes from a Slack request, put "Requested by: <Full Name>" on its
own line near the top of the PR description.

For more on resolution follow-ups, see Post status updates in Slack threads.

The fastest way to fix a message is to reply to it. When a notification misses, reply in its thread with a standing rule. For example: “From now on, don’t thank people in notifications.” Promptless records the rule in your Knowledge Base, and its next notification links the file it changed on a Recorded: line.

Check what Promptless recorded, and correct a rule that’s worded too broadly, as Teach conventions with feedback describes.