OrchStep for support engineers

Every support ticket starts with the same archaeology. What version are they on? Can their box reach the API? What do the last few hundred log lines say? You ask, they send the wrong thing, you ask again, and two round-trips later you finally have what you needed at the start. Then engineering bounces it back because the bundle is missing the one field they wanted.

The information you need is always the same. The order you collect it in is always the same. That's a workflow, not a conversation.

This post turns diagnostics collection and escalation into one OrchStep workflow — a runbook you run instead of a checklist you half-remember at 2am.

Two tasks: collect, then escalate

diagnose gathers the standard bundle in a fixed order. escalate runs diagnose first, then attaches severity and hands off — so an escalation can never go up without its diagnostics.

name: support-runbook
# Turn "can you send me your logs?" into one repeatable command.
defaults:
  account: acme

tasks:
  # `orchstep run diagnose --var account=acme`
  diagnose:
    steps:
      - name: identity
        func: shell
        do: echo "resolving account {{ vars.account }}"
      - name: version
        func: shell
        do: echo "app version 4.2.1 / api 4.2.0"
      - name: connectivity
        func: shell
        do: echo "ping api -> 200 in 84ms"
        retry:
          max_attempts: 3
          interval: "1s"
          backoff_rate: 2.0
      - name: logs
        func: shell
        do: echo "collected last 200 log lines"
      - name: bundle
        func: shell
        do: echo "wrote diagnostics bundle for {{ vars.account }}"

  # `orchstep run escalate --var account=acme`
  escalate:
    steps:
      - name: gather
        task: diagnose
      - name: severity
        func: shell
        do: echo "severity S2 (degraded)"
      - name: handoff
        func: shell
        do: echo "opened engineering ticket with the bundle attached"

The details that make this hold up:

• connectivity has a retry:. A flaky network check gets three attempts with backoff before it counts as a real failure — you don't escalate "can't reach API" when it was a one-off blip.
• escalate calls diagnose (task: gather). The bundle is collected the same way every time, so engineering stops bouncing tickets for missing fields.

Run it for whoever's on the line

orchstep run diagnose --var account=acme
orchstep run escalate --var account=acme

One account ID in, a complete, consistent bundle out. And before you escalate, you can show exactly what would be collected and attached — without touching the customer's system:

orchstep run escalate --var account=acme --dry-run

That dry-run is also your training material: a new support hire can read the plan and learn the runbook without shadowing someone for a week.

What you gained

This isn't a ticketing system and it won't talk to the customer for you. It removes the part of support that's pure rote — collecting the same signals in the same order — so your attention goes to the actual problem. If your product has one diagnostic command already, use that. When "gather the logs" is six steps you do from memory, write them down.

Where to go next

• Composition — escalate reusing diagnose
• Error Handling — retry for flaky checks
• Previewing with Dry Run — the runbook as a readable plan
• Variables & Outputs — per-account inputs with --var

Take the diagnostics you ask for on every ticket, put them in order in a diagnose task, and replace "can you send me your logs?" with a command.