diff --git a/src/content/docs/docs/troubleshooting/integration-connection-issues.mdx b/src/content/docs/docs/troubleshooting/integration-connection-issues.mdx new file mode 100644 index 00000000..0be55b65 --- /dev/null +++ b/src/content/docs/docs/troubleshooting/integration-connection-issues.mdx @@ -0,0 +1,148 @@ +--- +title: Integration Connection Issues +description: Resolve OAuth failures, permission errors, and app installation problems with Promptless integrations. +slug: docs/troubleshooting/integration-connection-issues +sidebar: + hidden: false + order: 24 +--- +import Accordion from '@components/fern/Accordion.astro'; + +This page helps you diagnose and fix problems when connecting or maintaining integrations with Promptless. + +## GitHub Integration Issues + + +**Symptoms**: You installed the Promptless GitHub App but it doesn't show as connected in the dashboard, or repositories aren't appearing. + +**Likely causes**: +- The app was installed to a different organization than the one you're logged into +- The app installation was started but not completed +- Browser caching issues + +**Solutions**: +1. Confirm you're logged into the correct Promptless organization at [app.gopromptless.ai](https://app.gopromptless.ai). +2. Check GitHub directly: go to your GitHub organization Settings → Integrations → Applications and verify Promptless appears in the list. +3. If the app appears in GitHub but not Promptless, try disconnecting and reconnecting from the [Integrations page](https://app.gopromptless.ai/integrations). +4. Clear your browser cache and refresh the page. + + + +**Symptoms**: Promptless reports permission errors, can't read repository contents, or can't create pull requests. + +**Likely causes**: +- The GitHub App doesn't have access to the specific repository +- Repository permissions were restricted during installation +- The repository is in a different organization + +**Solutions**: +1. In GitHub, go to Settings → Integrations → Applications → Promptless → Configure. +2. Check whether Promptless has access to "All repositories" or "Only select repositories." +3. If using selective access, add the missing repository to the list. +4. For organization-owned repositories, ensure the GitHub App is installed at the organization level, not just your personal account. + + + +**Symptoms**: PRs aren't triggering Promptless, or there's a delay between PR activity and Promptless response. + +**Likely causes**: +- Network issues between GitHub and Promptless +- Webhook configuration was modified +- GitHub Enterprise firewall blocking outbound webhooks + +**Solutions**: +1. Check webhook delivery status in GitHub: repository Settings → Webhooks → Recent Deliveries. +2. Look for failed deliveries (red X icons) and examine the response codes. +3. For GitHub Enterprise, ensure the Promptless IP addresses are whitelisted. See the [GitHub Enterprise Integration](/docs/integrations/github-enterprise-integration) guide. +4. If webhooks are failing consistently, contact [help@gopromptless.ai](mailto:help@gopromptless.ai). + + +## Slack Integration Issues + + +**Symptoms**: You @mention Promptless in Slack but nothing happens—no reaction, no response. + +**Likely causes**: +- The Promptless Slack app isn't installed in your workspace +- Promptless doesn't have access to the channel +- The Slack integration was disconnected + +**Solutions**: +1. Check the [Integrations page](https://app.gopromptless.ai/integrations) to confirm Slack shows as connected. +2. In Slack, try inviting @Promptless to the channel using `/invite @Promptless`. +3. If Slack was recently reconnected, you may need to re-invite Promptless to private channels. +4. Try using the Promptless message action (click the three dots on a message → "Update Docs") instead of @mention to verify the integration works. + + + +**Symptoms**: When Promptless responds in Slack, diff files aren't appearing as attachments. + +**Likely causes**: +- Slack permissions were revoked or changed +- OAuth scopes need to be re-authorized + +**Solutions**: +1. Go to the [Integrations page](https://app.gopromptless.ai/integrations) and re-authorize the Slack connection. +2. After re-authorizing, diff files should appear as thread attachments. +3. If the issue persists, contact [help@gopromptless.ai](mailto:help@gopromptless.ai). + + +## Microsoft Teams Integration Issues + + +**Symptoms**: Promptless doesn't respond to @mentions or message actions in Teams. + +**Likely causes**: +- The Promptless Teams app needs to be added to the specific team or channel +- The integration was disconnected +- Teams admin policies are blocking third-party apps + +**Solutions**: +1. Verify Teams shows as connected on the [Integrations page](https://app.gopromptless.ai/integrations). +2. Add the Promptless app to your team: in Teams, go to Apps → search "Promptless" → Add to a team. +3. Check with your Teams administrator if third-party app installations require approval. + + +## OAuth and Authentication Errors + + +**Symptoms**: When connecting an integration, you see an error after the OAuth authorization screen, or the browser redirects to an error page. + +**Likely causes**: +- Pop-up blockers interfering with the OAuth flow +- Session timeout during the authorization process +- Browser extensions blocking redirects + +**Solutions**: +1. Disable pop-up blockers temporarily for app.gopromptless.ai. +2. Try the connection process in an incognito/private browser window. +3. Ensure you complete the OAuth flow promptly—sessions can timeout if left idle. +4. If using a corporate proxy, confirm it allows connections to OAuth providers (github.com, slack.com, etc.). + + + +**Symptoms**: An integration that previously worked now fails, even though it still shows as connected. + +**Likely causes**: +- OAuth tokens expired and couldn't be refreshed +- Permissions were revoked in the third-party service +- The connected account no longer has access to the resources + +**Solutions**: +1. Disconnect the integration from the [Integrations page](https://app.gopromptless.ai/integrations). +2. Reconnect using an account that has the necessary permissions. +3. For GitHub, ensure the user reconnecting has admin access to the repositories Promptless needs. +4. For Slack, the reconnecting user should be a workspace admin or have permission to install apps. + + +## General Connection Tips + +When troubleshooting any integration: + +1. **Check the Integrations page first**: [app.gopromptless.ai/integrations](https://app.gopromptless.ai/integrations) shows the connection status for all services. + +2. **Review recent events**: The [Triggers page](https://app.gopromptless.ai/triggers) shows processing history and any errors. + +3. **Reconnect as a solution**: Many issues resolve by disconnecting and reconnecting the integration. This refreshes OAuth tokens and re-syncs permissions. + +4. **Contact support with details**: When reaching out to [help@gopromptless.ai](mailto:help@gopromptless.ai), include which integration is affected, what you expected to happen, and any error messages from the dashboard or third-party service. diff --git a/src/content/docs/docs/troubleshooting/suggestion-quality-issues.mdx b/src/content/docs/docs/troubleshooting/suggestion-quality-issues.mdx new file mode 100644 index 00000000..adb497c1 --- /dev/null +++ b/src/content/docs/docs/troubleshooting/suggestion-quality-issues.mdx @@ -0,0 +1,128 @@ +--- +title: Suggestion Quality Issues +description: Improve Promptless suggestions that miss context, don't match your style, or target the wrong files. +slug: docs/troubleshooting/suggestion-quality-issues +sidebar: + hidden: false + order: 25 +--- +import Accordion from '@components/fern/Accordion.astro'; + +This page covers issues where Promptless suggestions miss context, don't match your style, or target the wrong files. + +## Suggestions Miss Important Context + + +**Symptoms**: The suggestion omits key details that were clearly stated in the PR description, code comments, or Slack thread. + +**Likely causes**: +- The trigger didn't include enough context for Promptless to understand the full scope +- Related tickets or issues weren't linked +- Context sources aren't configured + +**Solutions**: +1. **Add more context to triggers**: Include detailed PR descriptions, link to relevant tickets, and reference related conversations. +2. **Connect context sources**: Configure [Linear](/docs/configuring-promptless/context-sources/linear), [Jira](/docs/configuring-promptless/context-sources/jira), or [Confluence](/docs/configuring-promptless/context-sources/confluence) so Promptless can pull additional information. +3. **Use follow-up messages**: After receiving a suggestion, reply in Slack or comment on the PR with the missing context. Promptless will incorporate it into an updated suggestion. + + + +**Symptoms**: Promptless creates content that contradicts existing docs or doesn't account for related features already documented. + +**Likely causes**: +- The doc collection's index may be outdated +- The relevant existing pages weren't identified during analysis + +**Solutions**: +1. **Provide explicit references**: In your trigger message, mention specific existing pages that relate to the update. +2. **Use feedback**: After receiving the suggestion, provide feedback explaining the relationship to existing content. Promptless learns from this for future suggestions. +3. **Check doc collection sync**: Verify your doc collection is properly synced on the [Settings page](https://app.gopromptless.ai/settings). + + +## Suggestions Don't Match Your Style + + +**Symptoms**: Suggestions use different phrasing, formality level, or terminology than your established docs. + +**Likely causes**: +- Promptless hasn't fully learned your documentation style yet +- Your docs have inconsistent voice across pages +- Voice Match isn't enabled + +**Solutions**: +1. **Enable Voice Match**: Contact our team to enable Voice Match for your organization. This feature analyzes your existing docs and fine-tunes suggestions to match. +2. **Provide style feedback**: When rejecting or editing suggestions, explain what didn't match your style. For example: "We use 'select' instead of 'click' and avoid second person." +3. **Update your style guide**: Add your preferences to the Agent Knowledge Base. See [How Promptless Learns Your Docs](/docs/configuring-promptless/doc-collections/how-promptless-learns-your-docs). + + + +**Symptoms**: Suggestions use different heading styles, list formats, callout types, or code block conventions than your docs. + +**Likely causes**: +- Promptless hasn't seen enough examples of your formatting patterns +- Your docs use custom components that Promptless isn't recognizing + +**Solutions**: +1. **Provide formatting feedback**: When editing suggestions, note the formatting changes you made. Promptless learns from these edits. +2. **Document your conventions**: Add formatting guidelines to your AGENTS.md file or the Agent Knowledge Base. +3. **Edit and approve**: Even if you need to adjust formatting, approving edited suggestions teaches Promptless your preferences over time. + + +## Suggestions Target Wrong Files or Locations + + +**Symptoms**: Promptless suggests changes to a page that isn't the right location for the content. + +**Likely causes**: +- Multiple pages cover similar topics +- The PR or trigger didn't specify where updates should go +- The relevant page has an unclear title or description + +**Solutions**: +1. **Be explicit about location**: In your trigger (PR description, Slack message, etc.), specify which page should be updated. +2. **Provide feedback**: Reject the suggestion with an explanation like "This should go in the API Reference section, not the Getting Started guide." +3. **Review page metadata**: Ensure your docs pages have clear, descriptive titles and frontmatter descriptions that help Promptless identify appropriate locations. + + + +**Symptoms**: Promptless proposes a new documentation page for content that should be added to an existing page. + +**Likely causes**: +- The existing page wasn't identified as relevant +- The trigger described the content as a new topic + +**Solutions**: +1. **Reference existing pages**: In your trigger, mention "Update the existing [Page Name] page" to guide Promptless. +2. **Provide feedback**: If Promptless creates a new page inappropriately, reject with feedback explaining where the content belongs. +3. **Check for duplicate content**: Review your docs for overlapping topics that might confuse page selection. + + +## Improving Suggestion Quality Over Time + +Promptless learns from your feedback. Here's how to make feedback most effective: + +### In Slack +Reply to suggestions with specific guidance: +- "Add the error codes we discussed earlier in the thread" +- "Use the same structure as the existing API endpoint documentation" +- "This should be more concise—one paragraph instead of three" + +### In GitHub +Comment on Promptless PRs with detailed requests: +- "Please use our standard callout format for the warning" +- "The code example should show Python, not JavaScript" +- "Include a link to the related configuration page" + +### In the Dashboard +Use the feedback features to: +- Highlight text and explain why it's wrong +- Approve with edits to show preferred phrasing +- Reject with explanation when the approach is wrong + +### Update the Agent Knowledge Base +For persistent preferences, add guidance to your [Agent Knowledge Base](/docs/how-to-use-promptless/agent-knowledge-base): +- Style conventions and terminology +- Page structure templates +- Content guidelines for different doc types + +The more specific your feedback, the faster Promptless adapts to your preferences. diff --git a/src/content/docs/docs/troubleshooting/trigger-issues.mdx b/src/content/docs/docs/troubleshooting/trigger-issues.mdx new file mode 100644 index 00000000..51930936 --- /dev/null +++ b/src/content/docs/docs/troubleshooting/trigger-issues.mdx @@ -0,0 +1,164 @@ +--- +title: Trigger Issues +description: Fix problems with PRs not triggering Promptless, Slack mentions not responding, and webhook failures. +slug: docs/troubleshooting/trigger-issues +sidebar: + hidden: false + order: 26 +--- +import Accordion from '@components/fern/Accordion.astro'; + +This page helps when Promptless doesn't respond to events that should trigger documentation work. + +## GitHub PR Triggers + + +**Symptoms**: A pull request was opened or updated, but Promptless didn't create a suggestion or acknowledge the PR. + +**Likely causes**: +- No pipeline is configured to trigger on this repository +- The PR doesn't match your trigger filters (directories, file types, topics) +- The trigger is set to fire after approval, not on PR open +- Webhook delivery failed + +**Solutions**: +1. **Check pipeline configuration**: Go to [Projects](https://app.gopromptless.ai/projects) and verify a pipeline exists for this repository with GitHub PR triggers enabled. +2. **Review trigger settings**: Check if the trigger has directory filters, file type filters, or repository topic filters that exclude this PR. +3. **Check trigger timing**: Some configurations trigger after first approval rather than on open. If your PR hasn't been approved, wait for approval or adjust the configuration. +4. **Verify webhook delivery**: In GitHub, go to the repository Settings → Webhooks and check recent deliveries for failures. +5. **Check the Triggers page**: Look at [app.gopromptless.ai/triggers](https://app.gopromptless.ai/triggers) to see if the event was received but filtered out. + + + +**Symptoms**: Promptless acknowledged the PR (with a reaction or comment) but didn't create a suggestion. + +**Likely causes**: +- Promptless analyzed the changes and determined they don't require documentation updates +- The changes are internal implementation details without user-facing impact +- The relevant documentation already covers this functionality + +**Solutions**: +1. **Check the Triggers page**: Find the event at [app.gopromptless.ai/triggers](https://app.gopromptless.ai/triggers) and review the reasoning for why no suggestion was created. +2. **Provide more context**: If you believe docs should be updated, @mention Promptless in the PR with specific instructions about what documentation needs to change. +3. **Use explicit requests**: Comment "@Promptless please update the API reference to document this new parameter" to override the automated decision. + + + +**Symptoms**: Some PRs in a repository trigger Promptless while others don't. + +**Likely causes**: +- Directory or file type filters are configured +- Repository topic filters are excluding certain PRs +- The non-triggering PRs don't modify files Promptless monitors + +**Solutions**: +1. **Review filter configuration**: In [Projects](https://app.gopromptless.ai/projects), check the trigger settings for path includes/excludes and file type filters. +2. **Compare triggering vs non-triggering PRs**: Look at what files were changed. Triggering PRs likely modify files that match your filters. +3. **Adjust filters**: If the filtering is too restrictive, update your pipeline configuration to include the desired directories or file types. + + +## Slack Triggers + + +**Symptoms**: You @mention Promptless in a Slack channel but nothing happens—no reaction, no acknowledgment. + +**Likely causes**: +- Promptless isn't in the channel +- The Slack integration is disconnected +- No pipeline is configured for Slack triggers +- The channel is private and Promptless wasn't invited + +**Solutions**: +1. **Invite Promptless to the channel**: Type `/invite @Promptless` in the channel. +2. **Check integration status**: Verify Slack shows as connected on the [Integrations page](https://app.gopromptless.ai/integrations). +3. **Check pipeline configuration**: Ensure a pipeline exists with Slack triggers enabled. +4. **Try the message action**: Click the three dots on a message and look for "Update Docs" or other Promptless actions. If actions appear but @mention doesn't work, the integration is connected but Promptless may need to be invited to the channel. + + + +**Symptoms**: When you click the three dots on a Slack message, you don't see Promptless actions like "Update Docs." + +**Likely causes**: +- The Promptless Slack app isn't installed in your workspace +- You're looking in a workspace where Promptless isn't connected + +**Solutions**: +1. **Check integration status**: Go to [Integrations](https://app.gopromptless.ai/integrations) and verify Slack is connected. +2. **Reinstall the Slack app**: If Slack shows as connected but actions don't appear, disconnect and reconnect the integration. +3. **Check workspace**: Make sure you're in the Slack workspace that's connected to your Promptless organization. + + + +**Symptoms**: You enabled passive listening for a channel, but Promptless doesn't pick up conversations that should trigger documentation work. + +**Likely causes**: +- The specific channel isn't added to passive listening configuration +- The conversation doesn't match the criteria Promptless uses to identify documentation needs +- Passive listening was recently enabled and hasn't synced + +**Solutions**: +1. **Verify channel configuration**: Check that the specific channel is selected in your passive listening settings. +2. **Allow time for sync**: After enabling passive listening, give it a few minutes to take effect. +3. **Use explicit triggers for important items**: If a conversation should definitely trigger docs, use @Promptless mention or the message action rather than relying on passive detection. + + +## Microsoft Teams Triggers + + +**Symptoms**: @mentioning Promptless in Teams doesn't produce a response. + +**Likely causes**: +- The Promptless app isn't added to the team or channel +- The Teams integration is disconnected +- Teams admin policies block third-party bots + +**Solutions**: +1. **Add Promptless to the team**: In Teams, go to Apps → search "Promptless" → Add to a team. +2. **Check integration status**: Verify Teams shows as connected on the [Integrations page](https://app.gopromptless.ai/integrations). +3. **Contact your Teams admin**: Some organizations require approval for third-party apps. Check if Promptless needs admin approval. + + +## API Triggers + + +**Symptoms**: Your API call to trigger Promptless returns a 200 status, but no suggestion is created. + +**Likely causes**: +- The API payload is missing required fields +- The instructions don't match any configured pipeline +- The trigger was processed but Promptless determined no update was needed + +**Solutions**: +1. **Check the API response**: The response includes a trigger event ID. Use this to find the event on the [Triggers page](https://app.gopromptless.ai/triggers). +2. **Review the payload**: Ensure your request includes meaningful instructions that specify what documentation should change. +3. **Check pipeline configuration**: Verify a pipeline exists that handles API triggers. +4. **Review the event details**: The Triggers page shows whether the event was processed and why no suggestion was created. + + + +**Symptoms**: API calls return 401 Unauthorized errors. + +**Likely causes**: +- The API key is missing from the request +- The API key was revoked or is invalid +- The Authorization header format is incorrect + +**Solutions**: +1. **Check header format**: The API key should be sent as `Authorization: Bearer YOUR_API_KEY`. +2. **Verify the key**: Go to [Settings](https://app.gopromptless.ai/settings) to view or regenerate your API key. +3. **Check for typos**: Ensure there are no extra spaces or characters in the key. + + +## General Trigger Debugging + +When troubleshooting any trigger issue: + +1. **Start with the Triggers page**: [app.gopromptless.ai/triggers](https://app.gopromptless.ai/triggers) shows all events Promptless received. If your event appears, you can see how it was processed. If it doesn't appear, the event wasn't received (likely a webhook or integration issue). + +2. **Check integration status**: The [Integrations page](https://app.gopromptless.ai/integrations) shows whether each service is connected. + +3. **Review pipeline configuration**: Go to [Projects](https://app.gopromptless.ai/projects) to verify triggers are enabled and configured correctly for your use case. + +4. **Look at successful triggers**: If some triggers work and others don't, compare what's different—repository, channel, file types, or configuration. + +5. **Contact support**: When reaching out to [help@gopromptless.ai](mailto:help@gopromptless.ai), include the event details (PR URL, Slack message link, or API request) so we can investigate. diff --git a/src/content/docs/docs/troubleshooting/troubleshooting.mdx b/src/content/docs/docs/troubleshooting/troubleshooting.mdx new file mode 100644 index 00000000..649ddf6c --- /dev/null +++ b/src/content/docs/docs/troubleshooting/troubleshooting.mdx @@ -0,0 +1,55 @@ +--- +title: Troubleshooting +description: Common issues with Promptless and how to resolve them. +slug: docs/troubleshooting/troubleshooting +sidebar: + hidden: false + order: 23 +--- +import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'; + +If Promptless isn't working as expected, this section helps you identify and fix the issue. Start with the symptom you're seeing, then follow the guidance to resolve it. + +## Quick Fixes + +Before diving into detailed troubleshooting, try these common solutions: + +- **Verify integration connections**: Check the [Integrations page](https://app.gopromptless.ai/integrations) to confirm all services show a connected status. +- **Check trigger configuration**: Review your [project settings](https://app.gopromptless.ai/projects) to ensure triggers are enabled for the repositories or channels you expect. +- **Look at recent events**: The [Triggers page](https://app.gopromptless.ai/triggers) shows all events Promptless has processed. Find your event to see its status and any error messages. + +## Troubleshooting by Topic + + + + + + + + + +## Still Need Help? + +If you can't resolve the issue using this guide, we're here to help: + +- **Email**: Reach us at [help@gopromptless.ai](mailto:help@gopromptless.ai) with details about what you're seeing. +- **Slack Connect**: If you have a shared Slack channel with us, post your question there for faster response. +- **Schedule a Call**: [Book time](https://cal.com/team/promptless/30m-all) with our team for hands-on troubleshooting. + +When contacting support, include: +- The trigger event or suggestion ID from the Promptless dashboard +- What you expected to happen +- What actually happened +- Any error messages you saw diff --git a/src/lib/generated/sidebar.json b/src/lib/generated/sidebar.json index c3ce81c7..edc5ae84 100644 --- a/src/lib/generated/sidebar.json +++ b/src/lib/generated/sidebar.json @@ -149,6 +149,27 @@ } ] }, + { + "label": "Troubleshooting", + "items": [ + { + "label": "Troubleshooting", + "slug": "docs/troubleshooting/troubleshooting" + }, + { + "label": "Integration Connection Issues", + "slug": "docs/troubleshooting/integration-connection-issues" + }, + { + "label": "Suggestion Quality Issues", + "slug": "docs/troubleshooting/suggestion-quality-issues" + }, + { + "label": "Trigger Issues", + "slug": "docs/troubleshooting/trigger-issues" + } + ] + }, { "label": "Integrations", "items": [