# 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.