Triage & Investigations
Relevant source files
The following files were used as context for generating this wiki page:
Triage & Investigations is a specialized workflow in Orcy designed to handle clustered signals, engineering findings, and orphan missions. The system utilizes automated scans to detect patterns—such as recurring CI failures or agent experience signals—and promotes them into structured Investigation Missions. This ensures that systemic issues are not just logged as individual pulses but are triaged, analyzed for root causes, and resolved through coordinated agent or human efforts.
The module provides a bridge between raw telemetry (Pulses) and actionable work units (Missions). By clustering signals based on a clusterKey, Orcy can identify high-frequency or cross-mission issues that require dedicated investigation. These investigations leverage deterministic templates to ensure consistency in how root causes are documented and how resolutions are applied to the habitat's broader knowledge base.
Core Architectural Components
The triage system is built on a scanning and publication architecture that detects anomalies and generates investigative work.
Triage Scanning Service
The triageScanService is responsible for monitoring the signal environment within a habitat. It primarily focuses on two types of scans:
- Signal Pattern Clustered Scan: Detects when three or more signals share a
clusterKeywithin a 7-day window. It aggregates provenance data, affected tasks, and agent IDs into aClusterPayload. - Agent Quality Degraded Scan: Evaluates agent performance against a habitat-defined threshold (default 40%) using a minimum sample size (default 5 tasks).
Sources: packages/api/src/test/triageScanService.test.ts:74-100, packages/api/src/test/triageScanService.test.ts:180-210
Triage Mission Publication
When a scan identifies a cluster, the publishTriageMission service creates a new mission. This process is atomic, ensuring that the mission, its investigative tasks, and the junction row in triage_cluster_missions are committed simultaneously.
The publication uses the TRIAGE_MISSION_TEMPLATE_ID ("c0a8triage-0000-4000-8000-triage0000001") to instantiate a standardized investigation mission.
Sources: packages/api/src/repositories/template.ts:37-37, packages/api/src/test/triageMissionPublication.test.ts:80-110
Triage Data Models & Resolutions
The system tracks investigations through specialized records and links resolutions back to signal clusters.
Data Structures
| Component | Description | Key Fields |
|---|---|---|
| ClusterPayload | Metadata for a detected cluster. | clusterKey, signalCount, agentIds, timeWindowDays |
| Triage Junction | Links missions to specific cluster keys. | habitatId, clusterKey, missionId, status |
| Resolution Record | Documents the outcome of an investigation. | rootCause, resolution, resolutionKind, resolvedById |
Sources: packages/api/src/test/triageMissionPublication.test.ts:60-70, packages/api/src/test/triageResolutions.test.ts:60-75
Proactive Suggestions
When a new cluster emerges, the system looks up historical resolutions in triage_resolutions using the clusterKey. If a match is found, the system embeds a "Proactive Suggestion" in the new mission's description, providing agents with immediate context on how similar issues were handled previously.
Sources: packages/api/src/test/triageResolutions.test.ts:100-125
Investigation Workflow
Investigations follow a structured lifecycle from detection to resolution.
Investigative Tasks
A standard triage mission includes a primary investigative task:
- Key:
investigate - Title:
Investigate cluster: {{clusterSubject}} - Description: Analyze root cause, recommend routing buckets, and post an analysis pulse.
- Required Capabilities:
investigation
Sources: packages/api/src/repositories/template.ts:400-415
Resolution Flow
The resolution process captures structured data about why an issue occurred and how it was fixed.
Triage API & MCP Tools
Orcy exposes triage capabilities through the orcy_triage MCP tool and REST endpoints.
MCP Triage Actions
| Action | Description | Parameters |
|---|---|---|
top_issues | Lists ranked cluster summaries by signal volume. | habitatId, limit |
investigate | Returns full context for a specific clusterKey. | habitatId, clusterKey |
resolution_lookup | Retrieves historical resolutions for a key. | habitatId, clusterKey |
map_orphan_mission | Positions orphan missions in the roadmap DAG. | habitatId, missionId, dependsOn |
Sources: packages/mcp/src/test/triage-dispatch.test.ts:35-80, packages/mcp/src/api.ts:1070-1110
Signal Surface API
The getSignalSurface API provides a projected view of habitat health, categorized into experiencePatterns (aggregated privacy-protected agent signals) and findings (structured engineering findings).
Sources: packages/mcp/src/api/interfaces.ts:545-560
Conclusion
Triage & Investigations provide Orcy with a reactive and proactive framework for maintaining habitat health. By automating the transition from ephemeral signals to permanent resolutions, Orcy ensures that agents can learn from systemic failures. The atomic publication of triage missions and the integration of historical resolutions into new investigative work units form a closed-loop system for continuous habitat improvement.