Concept
Investigations
An investigation is an analytical container that groups related tasks under a shared objective. It provides structure for complex, multi-step diagnostic work: define what you're looking for, form a hypothesis, execute tasks to gather evidence, and capture findings.
Structured analysis
Define an objective and hypothesis upfront. Tasks created under an investigation contribute to a shared evidence base.
Artifact collection
Notes, links, evidence, and summaries are attached directly to the investigation, surviving individual task completion.
Resolution tracking
Investigations move through open, in progress, resolved, and archived states. The summary captures final conclusions.
When to use an investigation
Investigations are the right tool when the work is analytical, multi-step, and uncertain. If you know exactly what command to run, a task is sufficient. If you need to explore, gather evidence, and form conclusions, use an investigation.
| Use a Task when | Use an Investigation when |
|---|---|
| You know exactly what to do | You need to figure out what's happening |
| Single command or prompt | Multiple tasks exploring a problem |
| Result is pass/fail | Result is a conclusion with evidence |
| No context needed beyond the intent | Hypothesis, findings, and artifacts matter |
Lifecycle
Investigation created with an objective and optional hypothesis. No tasks executed yet.
Tasks are being executed under this investigation. Evidence is being gathered.
Conclusion reached. The summary field captures findings. No more tasks should be created.
Historical record. Fully read-only. Available for reference and audit.
Structure
| Field | Purpose |
|---|---|
| title | Short name for the investigation (required) |
| objective | What you're trying to learn or prove (required) |
| hypothesis | A testable premise — what you think is happening (optional) |
| summary | Conclusions and findings, typically filled when resolving (optional) |
| status | Current lifecycle state |
Relationships
An investigation connects to the rest of the system through two relationships:
Investigation
├─ Tasks (via task.investigationId)
│ ├─ Task A — "Check error logs on prod-1"
│ ├─ Task B — "Run diagnostic script on staging"
│ └─ Task C — "Verify fix on prod-1"
│
└─ Artifacts (via artifact.investigationId)
├─ Note: "Error started after deploy v2.4.1"
├─ Link: "Related Sentry issue #4521"
└─ Summary: "Root cause: missing index on users table"When listing investigations, the API returns task summaries (active count, pending approvals, last activity) and artifact counts. This gives a quick overview without loading every detail.
Example workflow
Create investigation: "Checkout latency spike" with objective "Identify root cause of p99 latency increase in /api/checkout"
Set hypothesis: "Database connection pool exhaustion during peak traffic"
Create task (mode: prompt): "Analyze slow query logs on db-primary for the last 24 hours"
Review task output. Add artifact (note): "Found 3 queries > 5s, all hitting users.sessions table"
Create task (mode: command): "EXPLAIN ANALYZE SELECT ... FROM users.sessions WHERE ..."
Add artifact (evidence): "Missing index on sessions.expires_at confirmed"
Resolve investigation with summary: "Root cause: missing index on sessions.expires_at. Fix deployed in v2.4.2."
MCP tools and resources
| Tool | Scope | Description |
|---|---|---|
| list_investigations | mcp:read | List investigations with task summaries and artifact counts |
| get_investigation | mcp:read | Full investigation with linked tasks and artifacts |
| create_investigation | mcp:operate | Create a new investigation with objective and hypothesis |
Resources
tanjiren://investigations/{id}Investigation with related tasks and artifactsWorkflow prompt
investigate_task_executionGuided workflow for investigating a failed or stuck task