Imported from Ma-fee/diagnosisClaw (packages/xeno-agent/config/skills/case_document/SKILL.md). Install upstream with npx skills add Ma-fee/diagnosisClaw --skill case_document. Copyright stays with the author.

Case Document Skill

Overview

Provides templates, formats, and structural guidelines for creating professional fault case documentation. This skill is a template reference - it supplies the structure and formatting patterns, but the actual report generation must use the complete diagnostic context from the current agent's conversation history.

Critical Requirement: Contextual Generation

REQUIRED: Case reports MUST be generated by the calling agent (the agent with complete diagnostic conversation context), NOT delegated to a subagent or background task.

Why:

• Subagents cannot access the full diagnostic conversation history
• Summary data passed to subagents loses critical details (user responses, measurement values, decision rationale)
• Report quality depends on complete contextual information

Execution Mode: REFERENCE - This skill provides templates; the calling agent executes the generation.

When to Use

Reference this skill when the calling agent needs to create case documentation:

• Root cause has been identified and verified
• Corrective actions have been implemented
• Fault has been resolved and verified
• Knowledge needs to be captured for future reference

Source Attribution

Reference: Include citation capability for all factual claims in the report.

Requirements:

• All technical specifications cite source: [^1]: [title](uri)
• All case references include case ID and URI
• Use manual:// URIs for manuals, https:// for web resources
• Place references at first mention in each section
• Training or case study material is required
• Maintenance records require formal documentation

Using This Skill

For the Calling Agent

When you have completed a diagnostic session and need to create documentation:

1. Load this skill to access report templates and formatting guidelines
2. Use your conversation context - access the complete diagnostic history from your conversation
3. Apply templates - use the section templates provided by this skill
4. Generate in current context - produce the report directly (do NOT delegate)

Data Requirements

The calling agent should have collected during the diagnostic session:

Report Generation Process

1. Load case-document skill (REFERENCE mode)
   ↓
2. Select appropriate templates from skill
   ↓
3. Gather data from current conversation context
   ↓
4. Apply templates with actual diagnostic data
   ↓
5. Generate report IN CURRENT AGENT (not delegated)
   ↓
6. Present to user

Report Structure Templates

Use these templates as guides when creating the report.

Section 1: Executive Summary

Template

## Executive Summary

| Field | Value |
|-------|-------|
| **Equipment** | [Manufacturer] [Model] - [Type] |
| **Fault** | [Brief description] |
| **Root Cause** | [Primary cause identification] |
| **Resolution** | [Corrective action summary] |
| **Status** | [Resolved / Monitoring / Escalated] |
| **Downtime** | [Duration, if tracked] |
| **Documentation Date** | [Timestamp] |

### Key Findings
- [Primary technical finding]
- [Critical decision or observation]
- [Preventive recommendation]

### Recommended Actions
1. [Immediate action if any]
2. [Preventive maintenance recommendation]
3. [Follow-up monitoring suggestion]

Section 2: Equipment Information

2.1 Equipment Specifications

2.2 System Architecture

Include Mermaid diagram showing relevant system:

graph LR
    A[Component A] --> B[Component B]
    B --> C[Component C]
    C --> D[Fault Location]

Diagram guidelines:

• Show components relevant to fault path
• Highlight fault location visually
• Include flow direction (mechanical, electrical, fluid)
• Keep to 5-10 nodes for clarity

2.3 Component Details

Section 3: Fault Description

3.1 Initial Report

**Reported by**: [User/technician name if available]
**Date Reported**: [Timestamp]
**Initial Description**: [Original user description]

3.2 Symptom Analysis

3.3 Timeline

timeline
    title Fault Timeline
    section Discovery
        Initial Observation : [Timestamp]
        First Report : [Timestamp]
    section Diagnosis
        Information Gathering : [Duration]
        Diagnostic Execution : [Duration]
        Root Cause Confirmation : [Timestamp]
    section Resolution
        Repair Implementation : [Timestamp]
        Verification Testing : [Timestamp]
        Return to Service : [Timestamp]

Section 4: Diagnostic Process

4.1 Methodology

**Diagnostic Approach**: [Systematic troubleshooting / FTA / Half-split / Other]
**Tools Used**: [List diagnostic tools]
**References Consulted**: [Manuals, diagrams, standards]

4.2 Diagnostic Steps

4.3 Evidence Summary

**Physical Evidence**:
- [Visual observations]
- [Measurement data]
- [Component condition]

**Data Evidence**:
- [Parameter readings]
- [Alarm logs]
- [Performance records]

**Analytical Evidence**:
- [Pattern analysis]
- [Comparative analysis]

Section 5: Root Cause Analysis

5.1 Root Cause Identification

**Primary Root Cause**: [Clear, specific identification]
**Confidence Level**: [Percentage]
**Evidence Strength**: [Strong/Moderate/Circumstantial]

5.2 Failure Mechanism

Explain technical cause-effect chain:

1. [Initial cause]
   ↓
2. [Intermediate effect]
   ↓
3. [Observable symptom]

5.3 Contributing Factors

5.4 Fault Tree Analysis

graph TD
    TOP["Top Event: [Fault Description]"] --> OR1["OR Gate"]
    OR1 --> AND1["AND Gate: [Combination required]"]
    OR1 --> CAUSE1["[Alternative Cause 1]"]
    
    AND1 --> CAUSE2["[Contributing Factor 1]"]
    AND1 --> CAUSE3["[Contributing Factor 2]"]
    
    CAUSE2 --> BASIC1["[Basic Event 1]"]
    CAUSE3 --> BASIC2["[Basic Event 2]"]

Section 6: Corrective Actions

6.1 Immediate Actions

6.2 Repairs and Replacements

6.3 Adjustments and Settings

6.4 Repair Procedure Summary

**Safety Precautions**:
- [List safety steps taken]

**Key Steps**:
1. [Major repair step]
2. [Critical procedure point]
3. [Quality check]

**Torque Specifications**:
| Fastener | Torque | Unit |
|----------|--------|------|
| | | |

Section 7: Verification

7.1 Test Procedures

7.2 Performance Validation

**Parameter Verification**:
| Parameter | Pre-Repair | Specification | Post-Repair | Status |
|-----------|------------|---------------|-------------|--------|
| | | | | |

**Operational Test**:
- Duration: [Test run time]
- Conditions: [Load, environment]
- Observations: [Performance notes]
- Result: [Pass / Monitor / Fail]

7.3 Acceptance Criteria

**Criteria Met**:
- [ ] All symptoms resolved
- [ ] Parameters within specification
- [ ] No new issues introduced
- [ ] Safety systems functional
- [ ] Operational test passed

Section 8: Lessons Learned

8.1 Diagnostic Insights

**What Worked Well**:
- [Effective diagnostic approach]
- [Key decision or observation]

**What Could Be Improved**:
- [Earlier detection opportunity]
- [Tool/method limitation]

8.2 Prevention Recommendations

8.3 Knowledge Gaps Identified

**Documentation Needs**:
- [Missing manual information]
- [Unclear procedure]

**Training Opportunities**:
- [Skill gap observed]
- [Common mistake pattern]

Section 9: Attachments and References

9.1 Technical References

**Manuals Consulted**:
- [Manual name, section, revision]

**Standards Applied**:
- [Standard reference, version]

**Diagrams Referenced**:
- [Figure numbers from manuals]

9.2 Image References

**Diagnostic Images**:
- [Description and location if stored]

**Repair Documentation**:
- [Photos of repair process if applicable]

Section 10: Approval and Distribution

**Document Prepared By**: [System/Analyst]
**Review Status**: [Draft / Reviewed / Approved]
**Distribution**:
- [ ] Maintenance Records
- [ ] Knowledge Base
- [ ] Training Materials
- [ ] Management Report

**Retention**: [Retention period or standard]

Mermaid Diagram Guidelines

System Architecture Diagram

graph LR
    subgraph Input
        A[Air Intake]
        B[Fuel System]
    end
    
    subgraph Engine
        C[Combustion Chamber]
        D[Cylinder Block]
    end
    
    subgraph Output
        E[Exhaust]
        F[Power Output]
    end
    
    A --> C
    B --> C
    C --> D
    D --> E
    D --> F
    
    style C fill:#ffcccc

Style guidelines:

• Use style to highlight fault location
• Group related components with subgraph
• Keep arrows showing flow direction
• Use clear, short node labels

Fault Tree Diagram

graph TD
    TOP["Engine Overheating"] --> OR1{"OR Gate"}
    
    OR1 --> COOLANT["Coolant System Failure"]
    OR1 --> AIRFLOW["Airflow Restriction"]
    OR1 --> COMBUSTION["Combustion Issues"]
    
    COOLANT --> AND1{"AND Gate"}
    AND1 --> LEAK["Leak Exists"]
    AND1 --> LOW["Low Coolant Level"]
    
    LEAK --> BASIC1["Hose Degradation"]
    LOW --> BASIC2["No Recent Service"]
    
    classDef basic fill:#90EE90
    classDef intermediate fill:#FFD700
    classDef top fill:#FF6B6B
    
    class BASIC1,BASIC2 basic
    class LEAK,LOW,COOLANT intermediate
    class TOP top

Diagram types:

• Use graph TD for top-down fault trees
• Use graph LR for left-right system flows
• Use timeline for chronological sequences
• Use subgraph for logical grouping

Report Quality Standards

Completeness Checklist

• Executive summary captures key points
• Equipment specifications accurate and complete
• Fault timeline is clear and chronological
• Root cause is specific, not generic
• Evidence supports root cause identification
• Corrective actions are documented with specifications
• Verification proves resolution
• Lessons learned are actionable
• Diagrams are clear and accurate
• References are specific and verifiable

Language Guidelines

• Use specific technical terms
• Quantify where possible ("temperature exceeded 100°C" not "overheated")
• Use active voice for actions
• Avoid blame language
• Focus on facts and evidence

Formatting Standards

• Use tables for structured data
• Use Mermaid for diagrams
• Use hierarchical headers (H2, H3, H4)
• Bold critical values and findings
• Include units with all measurements

Integration Notes

Receiving from Systematic-Troubleshooting

Expected input structure:

diagnostic_session:
  context: {information_gathering output}
  plan: {diagnosis_planning report reference}
  execution:
    steps: [list of diagnostic actions taken]
    results: [measurements and findings]
  root_cause:
    identification: string
    confidence: number
    evidence: array
  resolution:
    actions: [repairs, replacements]
    verification: [test results]
    status: resolved|monitoring

Output Destinations

• Maintenance management system
• Training documentation library
• Knowledge base / Case database
• Engineering review process

Example Usage

User: "Document the excavator engine overheating case we just resolved"

Skill receives complete session data
↓
Generates all 10 sections
↓
Produces: professional_case_report.md