Resolution Step Drafting Prompt for Troubleshooting Guides

This prompt is designed for technical writers and support engineers who need to produce a consistent, structured resolution procedure for a specific, known error code. The core job-to-be-done is transforming a defined error condition and its diagnostic surface area into a step-by-step guide that includes prerequisite checks, diagnostic commands, fix actions, and verification steps. It is ideal for teams maintaining a service catalog where every error code must map to a single, reviewable source of truth for remediation.

Use this prompt when you have a well-defined error code, its triggering context, and knowledge of the system's diagnostic tools. The prompt template requires you to provide the error code, a description of the system context, and a list of available diagnostic commands or tools. It is not suitable for open-ended debugging sessions where the error surface is unknown, nor for generating runbooks that execute automated remediation scripts without human approval. The prompt includes explicit safety constraints to prevent the generation of destructive or irreversible instructions, such as database drops or filesystem wipes, without flagging them for mandatory human review.

Before using this prompt, ensure you have gathered the specific error code string, a clear description of the service or component where it occurs, and the approved set of diagnostic tools available to operators. The output will be a structured, markdown-formatted procedure that you should always review for technical accuracy and safety before publishing. Do not use this prompt to generate runbooks for fully automated remediation systems where no human is in the loop to approve high-risk actions.

This is the core prompt template for drafting a troubleshooting guide. It is designed to be copied directly into your prompt engineering environment or application code. The template uses square-bracket placeholders for all dynamic inputs, such as the error code, its technical description, and the target audience. Before using this prompt, you must have a clear understanding of the error's root cause and the system's architecture to populate the placeholders accurately. The prompt's primary directive is to generate actionable steps while enforcing strict safety checks to prevent the model from suggesting destructive or irreversible commands.

markdownCopy
You are a senior technical writer and SRE creating a troubleshooting guide for an internal developer audience. Your task is to generate a step-by-step resolution procedure for the error code [ERROR_CODE].

## Error Context
- **Error Code:** [ERROR_CODE]
- **Error Message:** [ERROR_MESSAGE]
- **Technical Description:** [TECHNICAL_DESCRIPTION]
- **Common Root Causes:** [COMMON_ROOT_CAUSES]
- **Affected Service/Component:** [AFFECTED_COMPONENT]
- **Target Audience:** [TARGET_AUDIENCE] (e.g., on-call SRE, support engineer, end-user)

## Safety Constraints (CRITICAL)
You must adhere to the following rules. Violating them could cause a production outage.
- **NEVER** suggest commands that are irreversible, destructive, or lead to data loss (e.g., `DROP TABLE`, `rm -rf`, `DELETE` without a `WHERE` clause, `purge` commands).
- **ALWAYS** include a prerequisite step to verify the environment, context, or impact before any fix action.
- **ALWAYS** recommend backing up relevant state or data before a state-changing action.
- If a safe automated fix is not possible, explicitly state that manual intervention or escalation is required.
- Prefix any command that changes state with a warning and a confirmation prompt.

## Output Structure
Generate the resolution guide using the following strict structure:

### 1. Diagnostic Check
[Provide a specific command, log query, or metric check to confirm the error's root cause.]

### 2. Prerequisites
- [List any required permissions, tools, or access.]
- [State any conditions that must be true before proceeding.]

### 3. Resolution Steps
[Provide a numbered list of steps. For each step, include:]
- **Action:** [What to do, with exact commands or UI navigation.]
- **Expected Result:** [What the user should see if the action succeeds.]
- **If Failure:** [What to do if the step fails, e.g., rollback, check a different path, or escalate.]

### 4. Verification
[Provide a specific command, query, or check to confirm the issue is fully resolved and the system is stable.]

### 5. Escalation Path
[If the above steps do not resolve the issue, specify the exact team, runbook link, or on-call rotation to contact.]

To adapt this template, replace each [PLACEHOLDER] with the specific details of the error you are documenting. The [COMMON_ROOT_CAUSES] placeholder is critical for guiding the model toward the correct diagnostic checks. For high-risk production environments, you should add a final validation step in your application harness that scans the generated output for forbidden destructive commands before it is published. The next section details how to wire this prompt into a reliable documentation generation pipeline.

The resolution step drafting prompt is designed to be embedded in a documentation generation pipeline, not used as a standalone chat interface. The typical integration pattern places this prompt after error code extraction and classification stages, feeding it a structured error object that includes the error code, HTTP status, common causes, and any diagnostic context already gathered. The prompt produces a complete resolution procedure, which then passes through automated validation before reaching a human technical reviewer. This pipeline approach ensures that every resolution step is traceable to a specific error code and that no destructive or irreversible instructions reach end users without explicit approval.

The implementation harness should enforce several critical safety and quality checks. Pre-generation validation must verify that the input contains all required fields: [ERROR_CODE], [ERROR_CONTEXT], [SYSTEM_ARCHITECTURE], and [DESTRUCTIVE_ACTIONS_BLOCKLIST]. Missing fields should halt the pipeline and return a clear error to the upstream system. Post-generation validation must scan the output for any commands matching the blocklist (e.g., rm -rf, DROP TABLE, DELETE FROM, irreversible configuration changes) and flag them for mandatory human review. Additionally, a schema validator should confirm that each resolution step includes the required fields: step_number, action_description, expected_output, verification_command, and safety_level. Steps missing verification commands or marked as safety_level: destructive should be routed to a review queue rather than published directly. Logging should capture the prompt version, model used, input error code, and validation results for audit trails.

For model selection, use a capable instruction-following model with strong reasoning and safety awareness. The prompt works well with Claude 3.5 Sonnet or GPT-4o when structured output mode is enabled. Avoid smaller or older models that may hallucinate dangerous commands or skip verification steps. Implement a retry strategy with exponential backoff for transient failures, but cap retries at three attempts. If the model consistently produces outputs that fail validation, escalate to a human writer rather than silently accepting degraded quality. The final integration step should store validated resolution procedures in your documentation system with metadata linking them to the source error code, the prompt version used, the reviewer identity, and the approval timestamp. This creates an auditable chain from error code definition to published remediation guidance.