Skip to content

Troubleshooting

Systematic Diagnostic Protocol

AI Tools:
ChatGPT + 3 moreWorks with ChatGPT, Claude, Gemini, Perplexity
Category: Problem Solving

Isolate a cause before you fix it: ranked differentials, cheapest tests first, a branched diagnostic path, then fixes with rollback.

Prompt Quality - 100/100 · Strong

The Prompt

systematic-diagnostic-protocol.md

You are a senior troubleshooting engineer running a systematic diagnostic protocol. Do not suggest a fix until the diagnostic phase is complete.

ISSUE:
{{issue}}

SYSTEM DETAILS:
{{system}}

WHAT CHANGED RECENTLY:
{{changed}}

ERROR DATA (if any):
{{errors}}

INSTRUCTIONS:
1. Build a differential list: 5 - 8 plausible causes, most to least likely, based on symptoms and recent changes.
2. For each cause, the single fastest test that would confirm or rule it out - something I can actually run, not "check the logs."
3. Sequence checks cheapest/fastest first.
4. Separate: DEFINITELY the cause from evidence given vs POSSIBLE but needs testing vs UNLIKELY, with a one-line reason each.
5. Give a step-by-step diagnostic path with decision branches ("if X, go to step Y; if not, go to step Z").
6. Only after the diagnostic path is complete, propose fixes for the top 2 most likely causes, each with a rollback plan.

OUTPUT FORMAT:
- Differential list (table: Cause | Likelihood | Fastest test)
- Diagnostic decision tree (numbered steps with branches)
- Proposed fixes for top 2 causes (with rollback)

CONSTRAINTS:
- Never suggest "just restart it" or "just reinstall" as a first step unless the differential genuinely points there.
- If evidence is insufficient, say exactly what additional information you need rather than guessing.
- Flag any check that could cause data loss or downtime before suggesting it.

Negative prompt

Included when you copy the prompt

Do not propose a fix before the diagnostic path is complete. Do not invent logs or stack details that were not provided. Do not default to restart/reinstall as step 1. Do not skip rollback plans on the proposed fixes.

The PromptUTF-8

Fill in your details below - this prompt updates as you type, then copy it.

Fill in your details

0 of 4 filled. Preview updates as you type - then copy the finished prompt (negative prompt included when present).

What's broken vs expected vs observed.

Stack, tools, versions, hardware, or process steps.

Deploys, updates, load, or 'nothing I know of'.

Logs, messages, or metrics.

systematic-diagnostic-protocol.md

Prompt preview

You are a senior troubleshooting engineer running a systematic diagnostic protocol. Do not suggest a fix until the diagnostic phase is complete.

ISSUE:
{{issue}}

SYSTEM DETAILS:
{{system}}

WHAT CHANGED RECENTLY:
{{changed}}

ERROR DATA (if any):
{{errors}}

INSTRUCTIONS:
1. Build a differential list: 5 - 8 plausible causes, most to least likely, based on symptoms and recent changes.
2. For each cause, the single fastest test that would confirm or rule it out - something I can actually run, not "check the logs."
3. Sequence checks cheapest/fastest first.
4. Separate: DEFINITELY the cause from evidence given vs POSSIBLE but needs testing vs UNLIKELY, with a one-line reason each.
5. Give a step-by-step diagnostic path with decision branches ("if X, go to step Y; if not, go to step Z").
6. Only after the diagnostic path is complete, propose fixes for the top 2 most likely causes, each with a rollback plan.

OUTPUT FORMAT:
- Differential list (table: Cause | Likelihood | Fastest test)
- Diagnostic decision tree (numbered steps with branches)
- Proposed fixes for top 2 causes (with rollback)

CONSTRAINTS:
- Never suggest "just restart it" or "just reinstall" as a first step unless the differential genuinely points there.
- If evidence is insufficient, say exactly what additional information you need rather than guessing.
- Flag any check that could cause data loss or downtime before suggesting it.
0 / 4 filledPreview

Examples

Example input

Issue: Staging deploys succeed; production deploys of the same SHA fail at "migrate" with exit 1. Started after we added a second prod replica yesterday. System: Rails 7.1, Postgres 15, GitHub Actions, Kamal. Changed: Added read replica; bumped a gem that touches ActiveRecord. Errors: PG::UndefinedColumn on users.last_seen_at during migrate. Column exists in staging. No error in app logs after the failed deploy.

What you should get

Differentials (most → least): (1) Migration ran against a replica or wrong DATABASE_URL. (2) Prod primary schema drift vs staging. (3) Migration not in the SHA we think we deployed. (4) Gem bump changes schema dump. (5) Search path / schema name mismatch. Fastest tests: Print DATABASE_URL host in the migrate step; \d users on primary vs replica; git show SHA:db/migrate. Path: If migrate host is the replica → fix URL, do not rerun against replica. If primary lacks the column → inspect schema_migrations, do not "just db:reset". If SHA mismatch → stop the pipeline. Fixes (only after isolation): Point migrate at primary; add a CI check that migrate host == primary. Rollback: revert the Kamal accessory env, do not roll back the gem until the host is confirmed.

When to use this prompt

Use it when

  • You need help with managers.
  • You need help with engineers.
  • You need help with operators.
  • You need help with founders.

Skip it when

  • You only need a one-line ask with no constraints, format, or context.
  • You cannot supply the fill-in details the template asks for.
  • A different category or tool-specific workflow fits the job better.

How to get a good result

Done when

Differentials (most → least): (1) Migration ran against a replica or wrong DATABASE_URL. (2) Prod primary schema drift vs staging. (3) Migration not in the SHA we think we deployed. (4) Gem bump changes schema dump. (5) Search path / schema name mismatch. Fastest tests: Print DATABASE_URL host in the migrate step; \d users on primary vs replica; git show SHA:db/migrate. Path: If migrate host is the replica → fix URL, do not rerun against replica. If primary lacks the column → inspect schema_migrations, do not "just db:reset". If SHA mismatch → stop the pipeline. Fixes (only after isolation): Point migrate at primary; add a CI check that migrate host == primary. Rollback: revert the Kamal accessory env, do not roll back the gem until the host is confirmed.

Common mistakes

  • Leaving issue, system, changed vague - the model then invents placeholders.
  • Asking ChatGPT, Claude, Gemini, or Perplexity for a shorter answer after a long structured prompt - that throws away the format rules.
  • Stopping when the first draft appears instead of checking it against the success criteria below.

FAQ

What do I fill in before I copy this prompt?
Replace these placeholders with your details: issue, system, changed, errors. Required fields are marked on the page. The prompt text updates as you type.
Which AI tools is this prompt written for?
It works best with ChatGPT, Claude, Gemini, Perplexity. Copy the filled prompt and paste it into the tool you already use.
What should a good result look like?
Differentials (most → least): (1) Migration ran against a replica or wrong DATABASE_URL. (2) Prod primary schema drift vs staging. (3) Migration not in the SHA we think we deployed. (4) Gem bump changes schema dump. (5) Search path / schema name mismatch. Fastest tests: Print DATABASE_URL host in the migrate step; \d users on primary vs replica; git show SHA:db/migrate. Path: If migrate host is the replica → fix URL, do not rerun against replica. If primary lacks the column → inspect schema…
What are common mistakes with this prompt?
Leaving issue, system, changed vague - the model then invents placeholders. Asking ChatGPT, Claude, Gemini, or Perplexity for a shorter answer after a long structured prompt - that throws away the format rules. Stopping when the first draft appears instead of checking it against the success criteria below.

Best for

  • Managers
  • Engineers
  • Operators
  • Founders

More prompts like this — same topic and style.