SuperBizAgent-java/openspec/changes/archive/2026-07-06-diagnosis-playbook-skills/decisions.md

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.