SuperBizAgent-java/openspec/changes/archive/2026-07-05-aiops-payload-query-augmentation/design.md

Context

AiOpsService.buildTaskPrompt(...) already distinguishes two modes:

• PAYLOAD_TARGETED: diagnose the supplied alert payload.
• AUTO_DISCOVERY: discover active alerts first.

In payload-targeted mode, the prompt includes alert fields, but it does not provide a normalized retrieval query for lookup_knowledge. The Agent may still call the tool, but the exact query is left to model behavior.

Goals / Non-Goals

Goals:

• Build a deterministic retrieval query from AIOps payload fields.
• Preserve the original payload fields in the prompt.
• Make the recommended knowledge query visible in prompt text for trace/debugging.
• Keep the Agent responsible for deciding when to call lookup_knowledge.

Non-Goals:

• Do not add automatic pre-Agent retrieval.
• Do not add verifier logic.
• Do not change tool invocation schema.
• Do not change L0/L1 retrieval internals.

Decisions

Decision 1: Prompt-Level Query Augmentation

Add a recommended knowledge query to the payload-targeted prompt instead of calling lookup_knowledge directly.

Rationale:

• The current AIOps flow is Agent-driven; tools remain explicit.
• Prompt-level augmentation is low risk and easy to inspect.
• It avoids introducing another hidden retrieval path that would complicate trace semantics.

Alternative considered: automatically call lookup_knowledge before invoking the Supervisor. This was rejected because it changes execution behavior and may create evidence that the Agent did not request.

Decision 2: Preserve Original Query Terms

The generated query includes raw alert/service/symptom terms rather than replacing them with broad domains.

Rationale:

• Alert name, service name, severity, and symptom are high-value retrieval terms.
• Broad categories such as infrastructure are useful hints but should not replace concrete terms.

Risks / Trade-offs

• [Risk] Prompt grows slightly longer. -> Mitigation: keep the query compact and skip blank fields.
• [Risk] The model may ignore the recommendation. -> Mitigation: make the instruction explicit and test prompt inclusion.
• [Risk] Query construction duplicates some summary fields. -> Mitigation: treat the retrieval query as a compact, tool-oriented view of the payload.