73 lines
5.2 KiB
Markdown
73 lines
5.2 KiB
Markdown
# Decisions: diagnosis-playbook-skills
|
|
|
|
## Discover
|
|
|
|
- Entry summary: extract high-frequency diagnosis workflows into versionable skills/playbooks and make agents load them progressively.
|
|
- Slug: `diagnosis-playbook-skills`.
|
|
- Scale: `standard`.
|
|
- Capability source: sm-flow built-in protocol for Discover; `grill-with-docs` evidence-driven behavior used by reading project docs and code instead of blocking on user questions.
|
|
|
|
## Context
|
|
|
|
- `devflow/index.md` hit related projects: `diagnosis-eval-harness`, `expand-diagnosis-eval-fixtures`, `evidence-trace-hardening`, `aiops-alert-scope-control`, `session-dedup-knowledge-map`, `executor-action-memory-relevance`.
|
|
- `devflow/glossary/CONTEXT.md` confirms `ReactAgent`, `ToolCall`, `DiagnosisRecord`, and current historical terminology; current architecture documents supersede old `diagnosis_record` as the primary model.
|
|
- `mvp/architecture/evolution-roadmap.md` defines Skill/Playbook as P1 and requires eval-backed, fallback-capable playbooks.
|
|
- `mvp/architecture/harness-quality-gates.md` requires Prompt contract, Tool boundary, Trace persistence, Verifier/rule evaluation, and eval baselines to remain authoritative.
|
|
- `mvp/eval/cases/diagnosis-cases.json` anchors initial playbooks: payment timeout, MySQL pool exhausted, Redis timeout, slow response, JVM memory risk.
|
|
|
|
## Grill Question Pool
|
|
|
|
| Dimension | Question | Mode | Resolution |
|
|
|---|---|---|---|
|
|
| Terminology | Should these artifacts be called Skill or Playbook? | evidence-driven | Use "diagnosis playbook skills": skills are the runtime mechanism, playbooks are the diagnosis workflow content. |
|
|
| Boundary | Should skills contain factual knowledge or workflow guidance? | evidence-driven | Skills contain workflow guidance; knowledge facts remain in `knowledge_base/`. |
|
|
| Acceptance | What proves the change works? | evidence-driven | Unit tests for catalog/tool behavior plus existing diagnosis eval compile/test stability. |
|
|
| Interface impact | Does this alter external API or DB contracts? | evidence-driven | No external API/DB change; L2 internal interface due new tool/service and agent methodTools change. |
|
|
|
|
No user-interview question is blocking because the user explicitly asked to implement the change and prior conversation already confirmed the intended direction.
|
|
|
|
## Impact Analysis
|
|
|
|
GitNexus MCP tools are not exposed in this environment, so required GitNexus impact analysis could not be run. Local substitute analysis:
|
|
|
|
- `ChatService.createReactAgent`, `buildChatPlannerAgent`, `buildChatExecutorAgent`, and `buildMethodToolsArray` are called by Chat controller paths and covered by `ChatServiceSequentialAgentTest` / smoke tests.
|
|
- `AiOpsService.buildPlannerAgent`, `buildExecutorAgent`, and private `buildMethodToolsArray` affect `POST /api/ai_ops` via `ChatController`.
|
|
- Risk level: medium. Prompt and tool availability changes may alter agent behavior, but no external API, DTO, DB, or status contract changes.
|
|
|
|
## Specify / Commit
|
|
|
|
- Cross-artifact alignment:
|
|
- brief/proposal goal -> proposal: aligned.
|
|
- proposal scope -> design: aligned.
|
|
- design decisions -> specs/tasks: aligned.
|
|
- specs observable behavior -> tasks: aligned.
|
|
- Interface impact: L2 internal interface.
|
|
- Commit status: `.committed` created after file integrity and consistency checks.
|
|
|
|
## Pre-apply Research
|
|
|
|
- Reference code:
|
|
- `src/main/java/com/superbiz/agent/service/ChatService.java`
|
|
- `src/main/java/com/superbiz/agent/service/AiOpsService.java`
|
|
- `src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java`
|
|
- `src/main/java/com/superbiz/agent/agent/tool/QueryLogsTools.java`
|
|
- `src/main/java/com/superbiz/agent/agent/tool/QueryMetricsTools.java`
|
|
- Tool pattern: Spring AI Alibaba `SkillsAgentHook` contributes the official `read_skill` ToolCallback from hooks.
|
|
- Prompt pattern: `SkillsInterceptor` from the hook augments model requests with compact skill metadata.
|
|
- Test pattern: service tests instantiate classes manually with `ReflectionTestUtils`; new dependencies must be injectable or optional enough for tests.
|
|
- Dependency check: local `1.1.0.0-RC2` jars do not contain `SkillsAgentHook`; `1.1.2.0` jars contain `com.alibaba.cloud.ai.graph.agent.hook.skills.SkillsAgentHook`, `ReadSkillTool`, `SkillRegistry`, and `ClasspathSkillRegistry`.
|
|
|
|
## Apply
|
|
|
|
- Capability source: `openspec-apply-change` guidance was loaded; implementation used local sm-flow/OpenSpec fallback because the work required direct file edits and the OpenSpec CLI was not needed for artifact discovery.
|
|
- Implemented `src/main/resources/skills/*/SKILL.md` for six diagnosis playbooks.
|
|
- Upgraded Spring AI Alibaba BOMs to `1.1.2.0`.
|
|
- Implemented `SkillConfig` with `ClasspathSkillRegistry` loading `classpath:skills`.
|
|
- Wired `SkillsAgentHook` into Chat single-agent, Chat Planner/Executor, and AIOps Planner/Executor agents.
|
|
- Removed custom prompt-catalog injection from active service paths; the official `SkillsInterceptor` now handles skill catalog injection.
|
|
- Kept Chat Verifier prompt unchanged.
|
|
- Removed the earlier local fallback `SkillCatalogService` and `ReadSkillTool` source files after switching to official Alibaba skills support.
|
|
- Verification command:
|
|
- `mvn -q "-Dtest=SkillCatalogServiceTest,ChatServiceSequentialAgentTest,AiOpsServiceTest,DiagnosisTraceEvaluatorTest" test`
|
|
- Verification result: passed.
|