# diagnosis-playbook-skills Specification

## Purpose

Provide versionable diagnosis playbook skills for high-frequency MVP troubleshooting flows, loaded through progressive disclosure so agents can follow scenario-specific evidence workflows without bloating every prompt.

## ADDED Requirements

### Requirement: Skill catalog SHALL expose diagnosis playbooks compactly

The system SHALL provide a compact skill catalog containing each playbook skill name and description.

#### Scenario: Planner or Executor receives available skill metadata

- **GIVEN** classpath skill folders exist under `skills/`
- **WHEN** Chat or AIOps Planner/Executor agents are built
- **THEN** their system prompts SHALL include a compact diagnosis skill catalog
- **AND** the catalog SHALL include skill names and descriptions only, not full skill bodies

### Requirement: Executor SHALL read full playbook instructions on demand

The system SHALL expose a `read_skill` tool to Executor agents for loading a full `SKILL.md` body by skill name.

#### Scenario: Executor reads an existing skill

- **GIVEN** a skill named `diagnose-mysql-connection-pool`
- **WHEN** the Executor calls `read_skill` with that name
- **THEN** the tool SHALL return the full skill instructions
- **AND** the result SHALL include the skill name

#### Scenario: Executor requests an unknown skill

- **WHEN** the Executor calls `read_skill` with an unknown name
- **THEN** the tool SHALL return a bounded error message
- **AND** the message SHALL list valid skill names

### Requirement: Playbook skills SHALL preserve evidence and verifier boundaries

The system SHALL keep skills as workflow guidance and keep factual evidence collection in existing evidence tools.

#### Scenario: Executor uses a playbook

- **WHEN** a diagnosis playbook applies to a user issue
- **THEN** the Executor SHALL use the playbook to decide evidence order and stop conditions
- **AND** factual claims SHALL still be supported by `lookup_knowledge`, `query_logs`, `query_metrics`, or alert tools
- **AND** Chat Verifier SHALL continue to validate only existing `tool_trace_summary`

### Requirement: Initial playbook set SHALL cover fixed MVP diagnosis cases

The system SHALL provide playbooks for the existing fixed diagnosis evaluation scenarios.

#### Scenario: Fixed diagnosis case has a matching playbook

- **WHEN** the case is payment timeout, MySQL pool exhaustion, Redis timeout, slow response, or JVM memory risk
- **THEN** a matching diagnosis skill SHALL exist
- **AND** the skill SHALL state required evidence tools and low-confidence behavior