Writing Technical WritingIntermediate30 minSaves 30 minutes

Create an On-Call Runbook for Recurring System Tasks

Q: Can this runbook handle tasks that involve interaction with multiple distinct systems?

Yes, it can. Ensure your `{{detailed_task_description}}` clearly outlines all systems involved and the sequence of interactions. The model will structure steps accordingly, covering each system.

Q: How can I ensure the runbook reflects our specific internal tooling and conventions?

In your `{{detailed_task_description}}`, explicitly mention the names of your internal tools, monitoring systems, and any specific command-line utilities. The model will incorporate these details into the steps.

Engineers on rotation need clear, actionable guides for recurring on-call duties. Generate a precise runbook to ensure any new team member can independently resolve common issues, reducing MTTR and cognitive load.

This prompt generates a detailed internal runbook for a specific, recurring on-call task. It's designed to be comprehensive enough for a new on-call engineer to follow independently, covering prerequisites, execution steps, verification, and troubleshooting, ensuring operational consistency and reducing reliance on tribal knowledge.

ChatGPT Claude Gemini

READY-TO-USE PROMPT

Copy Prompt

prompt.txt

Context:
Our engineering team utilizes an on-call rotation to maintain system stability and respond to incidents. Many tasks are recurring and predictable but often require specific knowledge that isn't always documented clearly. This leads to increased incident resolution times and reliance on experienced team members, particularly when new engineers join the rotation. The goal is to standardize these procedures so that a brand-new on-call engineer can follow the guide independently from start to finish.

Task:
Generate a comprehensive internal runbook for the recurring on-call task named '{{task_name}}'. This runbook must provide all necessary information for an on-call engineer to understand, execute, and verify the task without external assistance. The runbook should be self-contained and assume the reader has a general engineering background but no specific familiarity with this particular task or system.

The recurring on-call task is described as: '{{detailed_task_description}}'.

Constraints:
* **Tone:** Precise, clear, and respectful of the reader's intelligence. Avoid any jargon that isn't strictly necessary or not immediately defined within the document.
* **Audience:** Engineers on rotation, including those new to the team or the specific system involved. The runbook must be actionable and unambiguous for this audience.
* **Independence:** The runbook must contain sufficient detail for a brand-new on-call engineer to execute the task solo, without needing to ask for clarification from senior engineers or consult external, undocumented resources.
* **Completeness:** Include all information a user would need, from initial understanding to final verification and potential troubleshooting.
* **Safety:** Emphasize any critical steps, warnings, or potential pitfalls.

Output Format:
Produce the runbook as a single document structured with the following top-level headings and their respective content:

1. **Overview**: A concise summary of the task, its purpose, and expected outcome.
2. **Prerequisites**: A checklist of necessary access, tools, information, or conditions that must be met *before* starting the task.
3. **Execution Steps**: A numbered, step-by-step guide for performing the task. Each step should be granular, clear, and include command examples or UI navigation paths where applicable.
4. **Verification**: Instructions on how to confirm the task was successfully completed and the system is in the expected state. Include specific metrics, logs, or UI checks.
5. **Troubleshooting**: Common issues that might arise during or after execution, along with their symptoms and recommended solutions.
6. **Related Links**: Pointers to relevant internal documentation, dashboards, or system repositories.

Estimated results

DifficultyIntermediate

Setup time30 min

Time saved30 minutes

Best modelsChatGPT, Claude, Gemini

Best audienceSoftware-Development, IT-Operations

Editor's note

Why this prompt matters

Maintaining system stability often relies on engineers executing recurring operational tasks during on-call rotations. Without precise, self-contained documentation, these tasks can become bottlenecks. New team members or those unfamiliar with a specific system often struggle, leading to delays in resolution and an increased burden on senior engineers who must provide ad-hoc guidance. This scenario not only impacts Mean Time To Resolution (MTTR) but also creates unnecessary stress and inefficiency within the team.

This workflow addresses that critical gap by generating comprehensive runbooks. It's designed for technical writers, engineering leads, or even individual engineers tasked with documenting these essential procedures. The goal is to produce a guide so clear and complete that any on-call engineer, regardless of their prior exposure to the system or task, can follow it independently from start to finish.

Reach for this workflow whenever a recurring on-call task lacks a standardized, unambiguous procedure. It's particularly valuable for onboarding new engineers to the rotation, ensuring operational consistency across shifts, and reducing the institutional knowledge required to keep critical systems running smoothly. By formalizing these processes, teams can improve operational resilience and free up experienced personnel for more complex problem-solving.

Anatomy

Prompt engineering breakdown

Role

You are a senior technical writer specializing in internal engineering documentation, tasked with creating a runbook.

Context

The engineering team uses an on-call rotation. Many recurring tasks lack clear documentation, leading to longer incident resolution times and reliance on experienced staff. The goal is to create a standardized procedure for new on-call engineers.

Goal

Generate a comprehensive, self-contained runbook for the recurring on-call task named '{{task_name}}' so that any on-call engineer can execute it independently without prior system-specific knowledge.

Constraints

The runbook must maintain a precise, clear, and reader-respecting tone, avoiding unnecessary jargon. It must be actionable for engineers new to the team or system, ensuring complete independence for task execution. All information from understanding to troubleshooting must be included, with critical steps and warnings highlighted for safety.

Output format

The output is a single document with these top-level headings: Overview, Prerequisites, Execution Steps, Verification, Troubleshooting, and Related Links.

Why this structure works

This structure is effective because role priming immediately establishes the AI's persona as a senior technical writer, setting the expectation for quality and depth. Explicit constraints on tone, audience, and completeness guide the content generation precisely. The detailed structured output format ensures all critical sections of a professional runbook are consistently covered, making the document immediately usable for its intended purpose.

Pick your version

Prompt variations

BeginnerWorks with any model

When drafting a simple guide for straightforward tasks, or for an audience that prefers less technical detail and direct instructions.

prompt.txt

Act as a helpful guide creating a basic instruction manual. Your task is to write a simple runbook for the recurring on-call procedure called '{{task_name}}'. This guide should let anyone on call, even new team members, follow the steps easily. The task involves '{{simple_task_description}}'. Make sure to include a short overview, what you need before you start (prerequisites), clear steps to do the task, how to check if it worked, and what to do if something goes wrong. Keep the language easy to understand and avoid complicated words. The goal is for a new person to complete the task by themselves. Structure it with these sections: Overview, What You Need, How To Do It, How To Check, Problems & Solutions.

ProfessionalBest with chatgpt

For developing detailed, high-fidelity operational documentation for established engineering teams where precision and completeness are paramount.

prompt.txt

Assume the role of a senior technical writer specializing in internal engineering documentation. Your objective is to produce a runbook that enables any on-call engineer, regardless of prior experience with the specific system or task, to successfully execute a recurring operational procedure. Context: Our engineering team utilizes an on-call rotation to maintain system stability and respond to incidents. Many tasks are recurring and predictable but often require specific knowledge that isn't always documented clearly. This leads to increased incident resolution times and reliance on experienced team members, particularly when new engineers join the rotation. The goal is to standardize these procedures so that a brand-new on-call engineer can follow the guide independently from start to finish. Task: Generate a comprehensive internal runbook for the recurring on-call task named '{{task_name}}'. This runbook must provide all necessary information for an on-call engineer to understand, execute, and verify the task without external assistance. The runbook should be self-contained and assume the reader has a general engineering background but no specific familiarity with this particular task or system. The recurring on-call task is described as: '{{detailed_task_description}}'. Constraints: Tone: Precise, clear, and respectful of the reader's intelligence. Audience: Engineers on rotation, including those new to the team or the specific system involved. Independence: The runbook must contain sufficient detail for a brand-new on-call engineer to execute the task solo. Completeness: Include all information a user would need. Safety: Emphasize any critical steps. Output Format: Produce the runbook as a single document structured with the following top-level headings and their respective content: 1. Overview, 2. Prerequisites, 3. Execution Steps, 4. Verification, 5. Troubleshooting, 6. Related Links.

Short VersionBest with claude

When a concise, quick-reference guide is needed, or for initial outlining before a full document is developed.

prompt.txt

As a technical writer, create a concise runbook for '{{task_name}}', described as '{{brief_task_summary}}'. The aim is for any on-call engineer to perform this recurring task solo. Include a brief overview, essential prerequisites, main execution steps, how to verify success, and basic troubleshooting tips. Keep it direct and actionable, ensuring an engineer unfamiliar with the task can follow it without further assistance. Structure it simply with these key sections: Overview, Setup, Steps, Check, Fixes.

EnterpriseBest with gemini

For mission-critical systems, highly regulated environments, or tasks requiring formal process documentation, compliance adherence, and risk mitigation.

prompt.txt

Assume the role of a senior technical writer responsible for critical operational documentation within a regulated enterprise environment. Develop a comprehensive runbook for the recurring on-call task '{{task_name}}', described as '{{detailed_task_description}}'. This runbook must enable any on-call engineer to execute the task independently, while also addressing enterprise-level concerns. Include sections for compliance considerations, potential audit impacts, stakeholder notification protocols, and a clear risk assessment for each major step. The document must ensure operational continuity and adherence to internal governance policies. Constraints: Adhere to enterprise documentation standards, clearly identify compliance touchpoints, and detail risk mitigation strategies. Output Format: Overview, Regulatory & Compliance Notes, Prerequisites, Execution Steps (with identified risks and mitigation), Verification, Stakeholder Communication, Troubleshooting, Audit Trail Requirements, Related Links.

What you'll get

Expected output

Runbook: Rotate API Key for External Integration (Third-Party Service)

1. Overview This runbook details rotating the API key for our third-party-integration-service. This is a security compliance task, performed quarterly or on alert. It involves generating a new key, updating our internal secrets manager, deploying the service, and finally deactivating the old key.

2. Prerequisites

Access: External service console (API key management), internal secrets manager (write access for third-party-integration-api-key), deployment tool for third-party-integration-service, Grafana for monitoring.
Information: External service API key URL, secrets manager path, deployment pipeline name.

3. Execution Steps

Generate New API Key (External Service):

* Log into ThirdPartyService.com console. * Navigate to "API Keys". * Generate a new API key. Copy it. *Do not delete the old key yet.*

Update Internal Secrets Manager:

* Log into internal secrets manager (e.g., Vault UI). * Locate secret/third-party/integration/api-key. * Update value with new API key. Save.

Deploy `third-party-integration-service`:

* Initiate deployment via Jenkins job deploy-third-party-integration-service. * Monitor for successful completion.

Verify Integration Functionality:

* Check Third-Party Integration Service Dashboard in Grafana for successful API calls. * Confirm no new authentication errors. * Perform a manual test if possible (e.g., trigger a small data sync).

Deactivate/Delete Old API Key (External Service):

* *Only after successful verification in Step 4.* * Return to ThirdPartyService.com console. * Locate and deactivate/delete the *old* API key.

4. Verification

Service Logs: Check third-party-integration-service logs for 200 OK from external service; absence of 401 Unauthorized.
Dashboard: Confirm Third-Party Integration Service Dashboard shows normal operation, successful API call metrics, no error spikes.
Functional Test: Trigger a small, non-critical operation via integration to confirm end-to-end functionality with the new key.

5. Troubleshooting

`401 Unauthorized` Errors After Deployment:

* Symptom: Service logs show 401 Unauthorized. * Solution: 1. Verify new API key copied correctly to secrets manager. 2. Confirm third-party-integration-service deployment completed successfully. 3. Check external service console: new key active, old key not accidentally in use or deleted prematurely.

Deployment Failure:

* Symptom: Deployment pipeline fails. * Solution: Review deployment logs. Address configuration/dependency issues. Do *not* delete old key until service deploys successfully with new key.

6. Related Links

Under the hood

Why this prompt works

This prompt is effective because it employs several specific prompt engineering techniques to guide the model toward a highly structured and actionable output. First, role priming establishes the persona of a 'senior technical writer specializing in internal engineering documentation.' This immediately sets expectations for tone, precision, and the depth of technical detail required, moving beyond a general content generation task.

Crucially, explicit constraints are used to define the output's characteristics: tone, audience, independence, completeness, and safety. These constraints are not merely suggestions; they are non-negotiable requirements that force the model to consider the practical implications of an on-call scenario, ensuring the runbook is truly usable by a new engineer. The emphasis on 'independence' and 'completeness' directly addresses the core problem of undocumented institutional knowledge.

Finally, the structured output requirement, with its predefined top-level headings (Overview, Prerequisites, Execution Steps, Verification, Troubleshooting, Related Links), is fundamental. This structure ensures comprehensive coverage of all necessary aspects of an operational task, from initial understanding to post-execution checks and problem resolution. This systematic approach, combined with the demand for granular, step-by-step instructions and command examples, prevents the model from producing a superficial summary. A simple one-liner prompt would inevitably yield a high-level description, lacking the critical detail, safety warnings, and troubleshooting paths essential for a reliable on-call runbook.

Model fit

Best AI models for this prompt

ChatGPT

ChatGPT models are effective for generating structured content and can follow explicit formatting instructions well. They excel at breaking down complex processes into numbered steps and maintaining a consistent, precise tone. For this prompt, ensure your {{detailed_task_description}} is very specific to guide ChatGPT toward the necessary technical depth, as it may sometimes generalize if the input is too broad. See the full ChatGPT hub for deeper guidance.

Claude

Claude models handle extensive context windows efficiently, which is beneficial for detailed technical documentation like runbooks. They are adept at producing comprehensive, reader-respecting content while adhering to strict constraints regarding jargon and clarity. Claude tends to generate more thorough explanations and can better internalize the 'new on-call engineer' persona, leading to more robust troubleshooting sections. See the full Claude hub for deeper guidance.

Gemini

Gemini models are strong in producing clear, actionable instructions and can be particularly good at generating specific command-line examples or UI navigation paths when provided with enough detail in the prompt. Their ability to integrate different types of information (overview, steps, troubleshooting) into a cohesive document makes them suitable for runbook creation. Pay attention to the level of detail in the {{detailed_task_description}} to ensure the output is sufficiently granular. See the full Gemini hub for deeper guidance.

When to use

When onboarding new on-call engineers to ensure they can execute recurring operational tasks independently.
For standardizing procedures that currently rely on tribal knowledge or verbal instructions.
To reduce incident resolution times by providing clear, actionable steps for common issues.
When a specific recurring task frequently causes confusion or errors among on-call staff.
Before automating a task, to clearly define and document the manual steps involved.

When not to use

For one-off, highly experimental, or exploratory tasks that lack a defined procedure.
When the task requires significant architectural decisions or deep system debugging beyond routine operations.
If the underlying system or task is undergoing rapid, fundamental changes, making documentation quickly obsolete.
For tasks that are fully automated and require no manual intervention or verification steps.

Get more from it

Pro tips

1
Provide a highly detailed `{{detailed_task_description}}` including all necessary context, system names, and specific parameters to prevent vague output.
2
Explicitly list every prerequisite like access roles, specific tools, or required environment variables to avoid 'access denied' issues during execution.
3
Break down complex steps into granular, atomic actions with exact commands or UI navigation paths to prevent misinterpretation.
4
Include anticipated output or log snippets for each verification step to guide the engineer in confirming success and catching subtle failures.
5
Test the generated runbook with an engineer unfamiliar with the task to identify and correct any ambiguities or missing information.
6
Specify rollback procedures or safe exit points where applicable to mitigate risks from incomplete or erroneous task execution.

Don't ship this

Common mistakes

✗ Providing a generic `{{task_name}}` or `{{detailed_task_description}}` without specific context.
Fix — Be precise. Use 'Restart `billing-processor` service on `prod-web-01`' instead of 'Restart a service'. Include all relevant details.
✗ Omitting critical prerequisites like specific IAM roles, VPN access, or required CLI versions.
Fix — Assume zero prior knowledge. Explicitly list every single item an on-call engineer needs before starting the task.
✗ Describing execution steps at too high a level, lacking specific commands or UI paths.
Fix — Ensure each step is an atomic, executable action. Provide exact `ssh` commands, `kubectl` syntax, or UI navigation sequences.
✗ Failing to include concrete verification steps with expected outcomes, metrics, or log patterns.
Fix — Add clear checks. Detail which logs to tail, which metrics to monitor, or specific API calls to confirm task completion.
✗ Not addressing common failure modes or providing actionable troubleshooting advice within the runbook.
Fix — Anticipate issues. Include symptoms like 'Service still down' or 'Error 500' and specific, step-by-step fixes.
✗ Using internal jargon or acronyms without immediate definition, assuming reader familiarity.
Fix — Define all specialized terms upfront. Frame explanations for a reader new to the specific system or team context.

Frequently asked questions

Q.Can this runbook handle tasks that involve interaction with multiple distinct systems?

Yes, it can. Ensure your {{detailed_task_description}} clearly outlines all systems involved and the sequence of interactions. The model will structure steps accordingly, covering each system.

Q.What if the task requires sensitive credentials? Should I include them directly in the prompt?

No, do not include sensitive credentials. Instead, instruct the model to reference secure credential storage systems, like 'Retrieve credentials from HashiCorp Vault path secret/my-service/prod'.

Q.How long should the `{{detailed_task_description}}` be for optimal results?

Provide enough detail to fully describe the task, its scope, and any nuances. There's no strict length limit, but aim for clarity and completeness, typically 50-150 words for a moderately complex task.

Q.Is this prompt suitable for generating general incident response playbooks, not just recurring tasks?

While there's overlap, this prompt is optimized for recurring operational tasks with known procedures. Incident response playbooks often require more dynamic decision trees and diagnostic steps.

Q.Will the generated runbook include actual executable code or scripts?

No, it will not generate executable code. It will produce documentation that includes command-line examples and instructions for running existing scripts or interacting with system UIs.

Q.How can I ensure the runbook reflects our specific internal tooling and conventions?

In your {{detailed_task_description}}, explicitly mention the names of your internal tools, monitoring systems, and any specific command-line utilities. The model will incorporate these details into the steps.

Version 1.0Last reviewed July 8, 2026

Reviewed by PromptInFlow Editorial Team