OHDA Professional troubleshooting

Stop losing track of complex debugging sessions and "why did I try that?" moments. This skill implements the OHDA method (Observe, Hypothesize, Decide, Act) to turn technical troubleshooting into a replayable, structured worklog. It forces a disciplined loop that prevents skipping straight to actions before documenting the reasoning and expected outcomes.

What it does

• Enforces OHDA loops by requiring a formal sequence of Observation, Hypothesis, Decision, and Action for every technical intervention.
• Maintains replayable worklogs that document every command, timestamp, and raw output in an append-only Markdown format.
• Manages external citations by pinning git commits, package hashes, and specific timestamps to ensure documentation stays valid as code evolves.
• Tracks dead ends by striking through failed hypotheses rather than deleting them, preserving valuable "what not to do" data for the team.
• Automates lesson promotion by summarizing closed-out logs and linking them in project-level metadata like CLAUDE.md.

How it works

1. Initialize a new log file with a unique topic name and the ohda-YYYY-MM-DD prefix.
2. Execute loops by numbering steps (O1, H1, etc.) and documenting at least 2-3 hypotheses and candidate decisions before any mutation.
3. Commit mutations by writing the A: (Act) step with rollback instructions before running the command, then closing the loop with a fresh O:.
4. Close out the session by updating the TL;DR, performing a cold-reader check for local path leaks, and promoting the outcome to project memory.

Frameworks & tools

This tool operates via Markdown worklogs and integrates with local file systems and version control. It is designed to work within CLAUDE.md or similar project-context conventions.

Why this beats prompting it yourself

Generic troubleshooting prompts often lead to "fix-it" loops that disappear once the chat context clears. This skill enforces a specific IT industry standard for professional diagnosis that results in a permanent, searchable, and replayable asset for your entire team.

Use cases

• Deep-dive debugging where the root cause is non-obvious and requires multiple experiments.
• Incident post-mortems that need a step-by-step audit trail of what was changed and why.
• Handoffs and collaboration where a colleague needs to pick up a mid-diagnosis session without missing context.

Known limitations

Does not handle trivial one-shot fixes like typos. Requires a persistent file system to store logs and scripts.