orenlion1/investigation-skills

A root cause is rarely visible in one place. The latency spike and the logs
are in Grafana, the resources that were throttled underneath them are in AWS,
the deploy that preceded them is in a pull request, and the first customer
symptom is a Slack thread. Reading each store is easy; relating them is the
work — and when that work happens in a chat session, the conclusion survives
and the reasoning that produced it does not.
This repository keeps it. Describe the problem once in a task file; your coding
agent queries the resources in scope, draws the relationships between their
signals, narrows to a cause and a resolution, and writes the result up as a
report in which every material claim is pinned to the evidence behind it.
Publishing that report is what turns one person's investigation into something
the next lifecycle step — and the rest of the team — can build on.
The workflow is agent-driven. Anything shown as text below is something you
say to your coding agent while this repository is open — not a shell command.
The agent follows the repository policy and the skills
it routes to.
## Why use it
One entry point. open task produces a structured draft; saving and
closing the editor runs it. No per-investigation prompt engineering.
Correlation, not just collection. Metrics, logs, traces, AWS resource
state, code, tickets, and conversation are pulled onto one time window, so the
relationships between signals — not just the signals — are what you reason
about.
The systems you already use. AWS, Grafana, Slack, Bitbucket, Jira, and
Confluence are reached through scoped read-only skills — only the ones your
task actually names.
Access is part of the job, not a prerequisite. Each skill owns its own
sign-in and diagnoses its own failures, so an investigation does not stall on
an expired session or a profile that was never set up correctly.
Evidence you can audit. Reports keep inspected source, observed runtime
behavior, inference, and proposal apart, and link material claims to a
revision-pinned evidence index.
Deliverables, not notes. Markdown and PDF with consistent diagrams,
captions, stated limitations, and token accounting; optional one-command
publication to Confluence.
Work that compounds. A published report is the input to the next step of
the incident lifecycle and the record a teammate extends — instead of a
transcript that expires with the session, or the same alert investigated twice
by two people who never saw each other's notes.
Authorization stays with you. A task describes work. It never grants
permission to commit, update a ticket, deploy, or publish.
## Requirements
A coding agent that reads AGENTS.md or CLAUDE.md, a
working CodeGraph installation, and Python 3. Each integration's tooling and
sign-in live in its own skill. A missing required dependency is setup work
rather than a blocker — see
Required Dependencies.
The workflow works best in an IDE with the coding agent running in terminal
mode in the integrated terminal: the task draft opens in a waiting editor
beside the agent session, and closing that editor is what starts execution.
## Quick start
1. Open a draft. Ask the agent:
text
open task
It copies templates/TASK.md to a docs/tasks/TASK.md