# aiops-traceable-diagnosis-entry Specification

## Purpose
TBD - created by archiving change aiops-traceable-diagnosis-entry. Update Purpose after archive.
## Requirements
### Requirement: AIOps endpoint accepts optional alert input
The system SHALL allow `POST /api/ai_ops` to accept an optional JSON request body describing the alert diagnosis request.

#### Scenario: Caller supplies alert input
- **WHEN** a caller posts to `/api/ai_ops` with alert fields such as session id, alert name, service, severity, description, and time range
- **THEN** the AIOps analysis uses those fields to build the diagnosis task prompt and persisted session query

#### Scenario: Caller omits alert input
- **WHEN** a caller posts to `/api/ai_ops` without a body
- **THEN** the system still starts the default AIOps alert-analysis flow

### Requirement: AIOps session id is traceable
The system SHALL resolve a stable AIOps session id from the request when provided, otherwise generate one, and SHALL expose that session id to the SSE caller.

#### Scenario: Request includes session id
- **WHEN** a caller posts to `/api/ai_ops` with `sessionId`
- **THEN** the created `diagnosis_session.session_id` equals that value
- **AND** the SSE stream includes the same session id

#### Scenario: Request omits session id
- **WHEN** a caller posts to `/api/ai_ops` without `sessionId`
- **THEN** the system generates a session id
- **AND** the SSE stream includes the generated session id

### Requirement: AIOps report is persisted for trace replay
The system SHALL persist the final AIOps report into the existing `diagnosis_session.answer` field when a report is available.

#### Scenario: AIOps report is generated
- **WHEN** the AIOps planner/executor flow returns a final report
- **THEN** the corresponding diagnosis session is marked successful
- **AND** `diagnosis_session.answer` stores the final report
- **AND** `GET /api/diagnosis/{sessionId}/trace` can include that answer

### Requirement: AIOps trace uses existing evidence tables
The system SHALL continue using existing `agent_step` and `tool_invocation` persistence for AIOps trace evidence.

#### Scenario: AIOps uses evidence tools
- **WHEN** the AIOps flow calls available evidence tools
- **THEN** existing hooks and recorders persist agent steps and tool invocations under the resolved AIOps session id

### Requirement: AIOps payload prompts SHALL include a recommended knowledge query
When an AIOps request includes alert payload fields, the system SHALL include a deterministic recommended knowledge retrieval query in the prompt sent to the Agent flow.

#### Scenario: Payload-targeted prompt includes knowledge query
- **WHEN** an AIOps request contains alert name, service, severity, or description
- **THEN** the generated task prompt SHALL include a recommended `lookup_knowledge` query derived from the supplied payload fields

#### Scenario: Query skips blank fields
- **WHEN** some AIOps payload fields are blank
- **THEN** the recommended knowledge query SHALL omit those blank fields
- **AND** it SHALL preserve the non-blank alert-specific terms

#### Scenario: Auto-discovery prompt does not invent payload query
- **WHEN** an AIOps request does not include alert payload fields
- **THEN** the generated task prompt SHALL remain in auto-discovery mode
- **AND** it SHALL not include a payload-derived recommended knowledge query