Runbook Executor

Overview

This skill helps execute runbooks and document the execution with timestamped evidence. When a user runs through a runbook's steps, this skill generates a structured evidence file that captures what actually happened during execution, including results, deviations, issues, and validations.

Evidence files are stored alongside the runbook in timestamped directories, allowing multiple executions to be tracked over time without overwriting previous evidence.

Configuration

Evidence location pattern: <runbook-path>/evidence/<YYYY-MM-DD-HH-MM>/result.md

Example: ./runbooks/user-login-flow/evidence/2026-01-31-14-30/result.md

Evidence Structure

Each evidence file documents:

1. Execution Summary: Status, duration, environment, executor
2. Technical Requirements Verification: Confirmation of prerequisites
3. Step-by-Step Execution: Actual commands run, results obtained, timestamps
4. Validation Results: Database checks, API responses, UI verifications
5. Issues Encountered: Problems found and their resolutions
6. Deviations: Any differences from the documented runbook
7. Recommendations: Suggestions for improving the runbook
8. Conclusion: Overall assessment and follow-up actions

Instructions

When asked to execute a runbook and document evidence:

1. Run the evidence creation script: ./runbook-executor/scripts/create-evidence.sh <runbook-path>
2. Follow the runbook steps in <runbook-path>/STEPS.md
3. Document each step's execution in the generated evidence file
4. Capture actual commands, outputs, and results
5. Note any deviations or issues encountered
6. Complete all validation sections
7. Add screenshots or logs to the evidence directory if needed
8. Write the conclusion with overall assessment

When asked to review past executions:

1. Run the list script: ./runbook-executor/scripts/list-evidence.sh <runbook-path>
2. Review the list of executions ordered by date (newest first)
3. Open the relevant result.md file from the desired timestamp

Examples

Execute a runbook and create evidence:

./runbook-executor/scripts/create-evidence.sh runbooks/user-login-flow

Execute an API testing runbook:

./runbook-executor/scripts/create-evidence.sh runbooks/api-payment-flow

List all evidence executions for a runbook (newest first):

./runbook-executor/scripts/list-evidence.sh runbooks/user-login-flow

HTTP Requests in Runbooks

When a runbook contains HTTP requests that can be executed locally, create scripts using httpie to automate the requests and save responses for evidence.

Important: All scripts must be executed under supervision. Review each script before execution and verify the target endpoints are correct for your environment.

Structure for HTTP Scripts

<runbook-path>/
├── STEPS.md
├── scripts/
│   ├── activation.sh        # Environment setup and aliases
│   ├── .env                  # Secrets (git-ignored)
│   ├── .env.example          # Example configuration
│   ├── login.httpie.sh
│   ├── get-user.httpie.sh
│   └── responses/
│       ├── 1738500000-login.httpie.http
│       └── 1738500100-get-user.httpie.http
└── evidence/

Activation Script

The activation.sh script sets up the environment for HTTP scripts:

1. Loads environment variables from .env file (for secrets)
2. Creates the script-http function that wraps httpie and saves responses automatically

Usage

# First, activate the environment
source ./scripts/activation.sh

# Then run your scripts
./scripts/login.httpie.sh

Configuration with .env

Create a .env file for secrets (copy from .env.example):

cp .env.example .env

Example .env:

API_BASE_URL=https://api.example.com
API_USERNAME=your-username
API_PASSWORD=your-password
API_TOKEN=your-bearer-token

Script Requirements

Each httpie script should:

1. Use script-http instead of http directly
2. Use environment variables for secrets and configuration
3. Include a comment indicating to run source ./activation.sh first

Naming Convention

Response files follow this pattern:

<unix-timestamp>-<endpoint-name>.httpie.http

Examples:

• 1738500000-login.httpie.http
• 1738500100-get-users.httpie.http
• 1738500200-create-order.httpie.http

Example Script

#!/bin/bash
# Login API request using httpie
# Usage: source ./activation.sh && ./login.httpie.sh

set -e

BASE_URL="${API_BASE_URL:-https://api.example.com}"

script-http POST "$BASE_URL/login" \
    username="${API_USERNAME:-test@example.com}" \
    password="${API_PASSWORD:-secret123}"

Common httpie Commands

# GET request
http GET https://api.example.com/users -v

# POST with JSON body
http POST https://api.example.com/login username=user password=pass -v

# POST with custom headers
http POST https://api.example.com/data \
    Authorization:"Bearer token123" \
    -v

# PUT request
http PUT https://api.example.com/users/1 name="Updated Name" -v

# DELETE request
http DELETE https://api.example.com/users/1 -v

STEPS.md Integration

When documenting HTTP steps in STEPS.md, reference the activation and scripts:

## Step 1: Activate environment

\`\`\`bash
source ./scripts/activation.sh
\`\`\`

## Step 2: Authenticate with API

Execute the login script to authenticate:

\`\`\`bash
./scripts/login.httpie.sh
\`\`\`

Expected response: HTTP 200 with JWT token in response body.
Response saved to: `scripts/responses/<timestamp>-login.httpie.http`

Resources

• Template: assets/evidence-template.md
• Creation script: scripts/create-evidence.sh
• List script: scripts/list-evidence.sh
• Example httpie script: scripts/login.httpie.sh