Integration Troubleshooting FAQ Generation Prompt

This prompt is designed for support engineers and technical writers who need to transform a stream of resolved integration support tickets into a public-facing or internal troubleshooting FAQ. The core job-to-be-done is scaling documentation from support artifacts without losing technical precision. You provide raw ticket data, diagnostic logs, and integration context, and the prompt produces structured problem-cause-solution triples organized by symptom category. This is not a general-purpose summarization tool—it is a specialized harness for extracting resolvable root causes from messy support interactions and formatting them into a consistent, searchable knowledge base.

Use this prompt when you have a backlog of tickets for a specific integration surface (e.g., a payment gateway, identity provider, or shipping API) and need to produce documentation that helps users self-serve or helps new support engineers ramp faster. The ideal input includes the original user report, the internal diagnostic steps taken, the confirmed root cause, the resolution applied, and any relevant log patterns or error codes. The prompt works best when tickets have already been triaged and resolved; it is not designed for live troubleshooting or for generating speculative solutions. Do not use this prompt for tickets where the root cause was never confirmed, where the resolution was a temporary workaround without a permanent fix, or where the integration context is too sparse to distinguish between a product bug and a configuration error.

Before running this prompt, ensure your input data is clean and well-scoped. Group tickets by integration partner and symptom category to avoid mixing unrelated failure modes. The harness validates that every output entry links to a resolvable root cause, not a workaround, so tickets that ended with 'restarted the service and it worked' without further investigation will fail validation. Plan for human review of the generated FAQ to confirm technical accuracy, remove any residual customer-specific details, and ensure that diagnostic commands are safe to publish. If your ticket volume is high, consider batching by symptom category and running the prompt iteratively, then merging the outputs into a single structured FAQ document.

This prompt template transforms raw integration support tickets into a structured troubleshooting FAQ. It enforces a strict problem-cause-solution format, requires diagnostic commands and log patterns for each entry, and organizes output by symptom category. The template is designed to be dropped into an AI harness where [TICKET_CONTENT] is populated from your support system, [PRODUCT_NAME] scopes the integration context, and [KNOWN_ISSUES] provides existing documentation to avoid duplicates.

textCopy
You are a technical documentation engineer converting integration support tickets into a structured troubleshooting FAQ.

## INPUT
[TICKET_CONTENT]

## CONTEXT
Product: [PRODUCT_NAME]
Integration surface: [INTEGRATION_NAME]
Existing FAQ entries to avoid duplicating: [KNOWN_ISSUES]

## OUTPUT SCHEMA
Return a JSON array of FAQ entries. Each entry must have:
- "symptom_category": string (grouping label like "Authentication", "Rate Limiting", "Data Sync")
- "symptom": string (observable problem the user reports)
- "root_cause": string (the underlying technical cause, not a workaround)
- "resolution_steps": array of strings (ordered actions to resolve)
- "diagnostic_commands": array of strings (CLI, curl, or SQL commands to confirm the issue)
- "log_patterns": array of strings (grep-able log lines or error signatures)
- "applies_to_versions": string (version range or "all")
- "ticket_references": array of strings (anonymized ticket IDs for traceability)

## CONSTRAINTS
1. Every entry must link to a resolvable root cause. Do not document workarounds as root causes.
2. If the ticket describes a configuration error, the root cause must identify the specific misconfiguration.
3. If the ticket describes a third-party service failure, the root cause must state the external dependency and its failure mode.
4. Diagnostic commands must be copy-pasteable and safe to run in a non-production environment.
5. Log patterns must use literal strings or regex-compatible fragments.
6. If the ticket content is insufficient to determine a root cause, return an empty array and include a "needs_investigation" flag.
7. Do not include customer names, PII, or credential values in any output field.
8. Group entries by symptom_category in the output array.

## EXAMPLES
Input: "User reports 401 errors after rotating API keys. They updated the key in the dashboard but the integration still fails."
Output:
{
  "symptom_category": "Authentication",
  "symptom": "401 Unauthorized errors after API key rotation",
  "root_cause": "Stale API key cached in integration service; key rotation in dashboard does not trigger cache invalidation",
  "resolution_steps": [
    "Rotate the API key in the third-party dashboard",
    "Update the key in [PRODUCT_NAME] integration settings",
    "Restart the integration worker to clear the credential cache",
    "Verify with the diagnostic command below"
  ],
  "diagnostic_commands": [
    "curl -H 'Authorization: Bearer [NEW_KEY]' https://api.thirdparty.com/v1/status"
  ],
  "log_patterns": [
    "HTTP 401.*integration_worker",
    "credential_cache_miss.*key_id=[OLD_KEY_ID]"
  ],
  "applies_to_versions": "v2.1.0 and later",
  "ticket_references": ["TKT-1423"]
}

## RISK_LEVEL
Medium. Output is used in customer-facing documentation. Human review required before publication.

After pasting this template into your harness, replace [TICKET_CONTENT] with the raw support ticket body, [PRODUCT_NAME] with your product identifier, [INTEGRATION_NAME] with the specific integration surface, and [KNOWN_ISSUES] with a summary of existing FAQ entries to prevent duplication. The output is a JSON array ready for ingestion into your documentation pipeline. Validate every entry against the schema before publishing, and flag any entry where the root cause field describes a workaround rather than an underlying cause. For high-severity issues, route the generated FAQ entry through a subject-matter expert review before it reaches customers.

This prompt is designed to operate inside a support-ticket-to-knowledge-base pipeline, not as a one-off chat interaction. The typical flow begins when a support ticket is resolved and marked as a candidate for FAQ conversion. An automation rule or manual trigger sends the ticket's structured data—symptom description, diagnostic steps, root cause, and resolution—into the prompt template. The model returns a structured FAQ entry that must pass validation before it reaches a human reviewer or the public knowledge base.

Input assembly requires extracting the following from the source ticket: [SYMPTOM] (user-reported behavior), [DIAGNOSTIC_COMMANDS] (exact commands run), [LOG_PATTERNS] (relevant error signatures), [ROOT_CAUSE] (confirmed explanation), and [RESOLUTION] (steps that fixed the issue). If any of these fields are missing, the pipeline should either query the support engineer for completion or abort the FAQ generation. Never allow the model to invent diagnostic commands or log patterns to fill gaps—this is the most common failure mode in production.

Validation layer must enforce three hard rules before the output proceeds: (1) every FAQ entry must contain a root_cause field that describes a resolvable cause, not a workaround or symptom restatement; (2) every diagnostic_commands array must contain at least one concrete, runnable command with an expected output description; (3) no entry may contain unresolved ticket IDs, customer PII, or internal system paths. Implement these as post-generation checks using a combination of schema validation (JSON Schema on the structured output) and regex-based PII scanning. If validation fails, retry the prompt once with the validation errors appended as [CONSTRAINTS] feedback. If it fails twice, route to a human reviewer with the failure context attached.

Model choice and configuration matters here. Use a model with strong instruction-following and structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set temperature low (0.0–0.2) because FAQ entries require deterministic, reproducible structure. Enable structured output mode if your provider supports it, binding the response to a schema that enforces the problem, cause, solution triple plus category, diagnostic_commands, and log_patterns arrays. Do not use streaming for this workflow—you need the complete, validated object before any downstream action.

Human review and publication gates are essential because this content becomes customer-facing documentation. After validation passes, route the generated FAQ entry to a review queue where a support engineer or technical writer can verify accuracy, edit for clarity, and approve publication. The review interface should display the original ticket context alongside the generated FAQ so the reviewer can confirm fidelity. Once approved, publish to the knowledge base and link the FAQ entry back to the source ticket for traceability. Avoid fully automated publication unless you have a high-confidence eval score and a rollback mechanism for incorrect entries.