Filter noise and tune relevance
Overview
Section titled “Overview”When Promptless suggests docs for internal refactors and config bumps, reviewers start ignoring its suggestions. Tune for relevance so that most suggestions you see are ones worth publishing. Narrow what reaches Promptless in the first place, then teach it, over time, which changes your team doesn’t document.
Promptless filters at three points, from earliest to latest:
- What triggers analysis. Scope your triggers so only documentation-worthy events reach Promptless.
- What Promptless skips automatically. Built-in filters drop changes that are never documentation-worthy.
- What you teach it to skip. Feedback on suggestions changes what Promptless proposes next time.
Start with trigger scope. A change that matches no trigger never becomes a suggestion.
Before you start
Section titled “Before you start”- An admin role in your Promptless organization, to edit triggers on the Configuration page and files in the Agent Knowledge Base.
Scope what triggers analysis
Section titled “Scope what triggers analysis”Each trigger on the Configuration page defines the events Promptless watches. The settings below matter most for relevance. The Configuration reference documents the full set.
Watch only the directories that change docs
Section titled “Watch only the directories that change docs”Limit a GitHub pull request trigger to the folders that affect your documentation, such as src/ or api/. Promptless then considers only pull requests that change files in those folders. A pull request that changes only tests/ or infra/ produces no suggestion.
-
On the Triggers tab of the Configuration page, expand a GitHub pull requests trigger.
-
Open More filters (optional).
-
Select Only when files in these folders change, and enter the folder paths.
-
Select Save changes.
In YAML, set the trigger’s trigger_directories list. See Limit a trigger to specific directories.
Watch only the repositories that matter
Section titled “Watch only the repositories that matter”If your organization has many repositories, most of them never need documentation. Two filters under More filters (optional) keep a trigger focused:
- Only repos tagged with these GitHub topics. Enter one or more GitHub topics, such as
docs-watch. Promptless triggers on any repository that has at least one of them. To add or remove a repository, change its topics in GitHub. Your configuration stays the same. See Limit a trigger to tagged repositories. - Skip these repositories. Watch a broad set of repositories and list the noisy ones here. Those repositories never trigger a suggestion. In YAML, this is the
excluded_reposlist. See the Configuration reference.
Trigger later in the release cycle
Section titled “Trigger later in the release cycle”The event a trigger runs on decides how often Promptless runs, and how finished a change is when it does. When it’s opened runs on every new pull request. When it’s first approved waits until a reviewer has approved the change, and When it’s merged waits until it lands. A later event means fewer runs, on changes that are closer to final. See Time suggestions to your release cycle.
Know what Promptless skips automatically
Section titled “Know what Promptless skips automatically”Promptless drops some changes before it creates a suggestion. These filters always apply, and there’s nothing to configure:
- Draft pull requests. Promptless waits until a pull request is marked ready for review. An
@promptlessmention on a draft still starts work. - Pull requests Promptless opened. Promptless skips its own docs PRs.
- Tooling-only changes. Promptless skips a pull request that changes only dot-directories, such as
.github/or.circleci/, or root-level dot-files, such as.gitignore. These are usually CI and tooling configuration. A pull request that also changes other files gets a normal review. - Changes with no documentation impact. For every triggered event, Promptless assesses whether the change needs documentation before it creates a suggestion. A change that touches no documented behavior produces no suggestion.
When Promptless decides a change needs no documentation, the decision appears on the Triggers page in your dashboard. You can tell a considered “no” from a missed event. See Follow what a trigger did.
Teach Promptless what to skip
Section titled “Teach Promptless what to skip”Trigger scope handles the broad cuts. Some changes touch documented behavior, but your team never documents them. Teach Promptless those judgment calls directly: write standing guidelines up front, and refine them through feedback as suggestions come in.
Write standing guidelines in your Knowledge Base
Section titled “Write standing guidelines in your Knowledge Base”Some sources mix documentation-worthy messages with noise no filter can catch. For example, a Slack channel that Promptless passively listens to carries both questions worth documenting and chatter that isn’t. Tell Promptless what to act on before it drafts anything:
-
In the Promptless dashboard, open Settings and select Agent Knowledge Base.
-
Open
PROMPTLESS.md. -
Add guidelines that say what to act on, what to ignore, and how to handle recurring edge cases. For example:
-
“In #support, document answers to how-to questions; ignore status updates and incident chatter.”
-
“When a thread resolves a bug, capture the workaround, not the back-and-forth.”
-
“Treat any message prefixed with
asideas out of scope.”
-
-
Select Save.
Promptless reads PROMPTLESS.md at the start of every task, so it applies these guidelines before it drafts a suggestion. See Agent Knowledge Base.
Close a suggestion with a reason
Section titled “Close a suggestion with a reason”When a suggestion isn’t worth keeping, close it and select the reasons that fit. These reasons map directly to noise:
- This change is too insignificant
- This change is self-explanatory and doesn’t need docs
- This change was covered in another Promptless suggestion
- This is already in my docs
Leave Send to Promptless checked so Promptless reads your reasons. See Close a suggestion with feedback.
State what to skip as a standing rule
Section titled “State what to skip as a standing rule”To have Promptless skip a kind of change on every future suggestion, state a standing rule in your feedback. For example, in close feedback or a comment:
- “Don’t create suggestions for dependency bumps.”
- “Internal-only tooling changes never need docs.”
Promptless records the rule in your Agent Knowledge Base and applies it to later suggestions. See Teach conventions with feedback.
Quiet the notifications, not the suggestions
Section titled “Quiet the notifications, not the suggestions”Sometimes the suggestions are right but the alerts are too loud. Notification settings change who hears about a suggestion, and not which suggestions Promptless creates:
- To change when and where Promptless notifies your team, see Customize notifications.
- To turn off the comments Promptless posts on source pull requests, see Suppress source PR comments.
See also
Section titled “See also”- Teach conventions with feedback, to make a rule apply to every future suggestion
- Time suggestions to your release cycle, to choose the event that triggers Promptless
- GitHub PRs, for every rule Promptless checks before it reviews a pull request
- Customize notifications, to change who hears about suggestions