Fiber Link Failure Audit Report Generator

What I Do

Generate professional, standardized HTML audit reports for fiber optic link failures detected by ADVA FSP3000 ALM devices. Each report includes:

Executive summary with status and action items
OTDR baseline vs current comparison diagram (PNG)
Detailed failure localization and root cause analysis
Technical measurements and parameters
Actionable recommendations

When to Use Me

Invoke when:

Investigating active alarms on ALM-monitored ports
Creating post-incident documentation
Generating audit reports for field crews
Documenting fiber link failures

Investigation Workflow

1. Get Alarm Context

// List all active alarms
const alarms = await alm_list_alarms()

// Get specific port details
const portInfo = await alm_get_port({ port_number: X })

// Get measurement history
const history = await alm_get_measurement_history({
  port_id: X,
  limit: 20
})

2. Download Baseline and Current Traces

CRITICAL: Always specify trace_type to avoid timeouts.

// Download baseline fingerprint
await alm_download_trace_to_file({
  port_id: X,
  measurement_id: BASELINE_ID,
  trace_type: "fp",  // fingerprint
  format: "csv",
  output_path: "./baseline.csv"
})

// Download fault analysis trace
await alm_download_trace_to_file({
  port_id: X,
  measurement_id: CURRENT_ID,
  trace_type: "fa",  // fault analysis
  format: "csv",
  output_path: "./fault.csv"
})

3. Generate OTDR Diagram

MANDATORY: Use the custom tool - DO NOT use Chart.js.

await generate_alm_diagrams({
  port_id: X,
  baseline_csv: "./baseline.csv",
  current_csv: "./fault.csv",
  failure_distance: 32000,  // meters, optional
  timestamp: "2025-10-31",  // YYYY-MM-DD
  output_dir: "./"
})

Output: otdr_baseline_comparison.png (baseline=green, current=red)

4. Create HTML Report

Generate REPORT.html with this EXACT structure:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Fiber Link Failure Audit Report - Port {PORT_NUMBER}</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
      line-height: 1.6;
      max-width: 1200px;
      margin: 0 auto;
      padding: 20px;
      background: white;
      color: #333;
    }

    h1 {
      color: #1a1a1a;
      border-bottom: 3px solid #2196F3;
      padding-bottom: 10px;
    }

    h2 {
      color: #2c3e50;
      margin-top: 30px;
      border-bottom: 2px solid #e0e0e0;
      padding-bottom: 8px;
    }

    h3 {
      color: #34495e;
      margin-top: 20px;
    }

    .status-badge {
      display: inline-block;
      padding: 8px 16px;
      border-radius: 4px;
      font-weight: bold;
      margin: 10px 0;
    }

    .status-resolved { background: #4CAF50; color: white; }
    .status-active { background: #F44336; color: white; }
    .status-degraded { background: #FF9800; color: white; }

    table {
      width: 100%;
      border-collapse: collapse;
      margin: 20px 0;
      background: white;
    }

    th, td {
      padding: 12px;
      text-align: left;
      border: 1px solid #ddd;
    }

    th {
      background: #f5f5f5;
      font-weight: 600;
      color: #2c3e50;
    }

    tr:nth-child(even) {
      background: #fafafa;
    }

    .diagram-container {
      margin: 30px 0;
      padding: 20px;
      background: #f9f9f9;
      border: 1px solid #e0e0e0;
      border-radius: 4px;
    }

    .diagram-container img {
      max-width: 100%;
      height: auto;
      display: block;
      margin: 0 auto;
      background: white;
    }

    .recommendation {
      background: #E3F2FD;
      border-left: 4px solid #2196F3;
      padding: 15px;
      margin: 15px 0;
    }

    .critical {
      background: #FFEBEE;
      border-left: 4px solid #F44336;
      padding: 15px;
      margin: 15px 0;
    }

    code {
      background: #f5f5f5;
      padding: 2px 6px;
      border-radius: 3px;
      font-family: 'Courier New', monospace;
    }

    .metadata {
      color: #666;
      font-size: 0.9em;
      margin-top: 40px;
      padding-top: 20px;
      border-top: 1px solid #e0e0e0;
    }
  </style>
</head>
<body>

<h1>Fiber Link Failure Audit Report</h1>

<h2>Executive Summary</h2>
<p><strong>Port:</strong> {PORT_NUMBER} - {PORT_NAME}</p>
<p><strong>Investigation Time:</strong> {TIMESTAMP}</p>
<div class="status-badge status-{STATUS_CLASS}">{STATUS_TEXT}</div>
<p><strong>Required Action:</strong> {ACTION_TEXT}</p>

<h2>Incident Details</h2>
<table>
  <tr>
    <th>Port</th>
    <td>{PORT_NUMBER} - {PORT_NAME}</td>
  </tr>
  <tr>
    <th>Alarm Type</th>
    <td>{ALARM_TYPE}</td>
  </tr>
  <tr>
    <th>Severity</th>
    <td>{SEVERITY}</td>
  </tr>
  <tr>
    <th>Detection Time</th>
    <td>{ALARM_TIMESTAMP}</td>
  </tr>
  <tr>
    <th>Link Length</th>
    <td>{LINK_LENGTH} meters</td>
  </tr>
</table>

<h2>OTDR Analysis</h2>

<div class="diagram-container">
  <h3>Baseline vs Current Comparison</h3>
  <img src="./otdr_baseline_comparison.png" alt="OTDR Baseline vs Current Trace Comparison">
  <p style="text-align: center; color: #666; margin-top: 10px;">
    <strong>Green:</strong> Baseline Fingerprint | <strong>Red:</strong> Current Measurement
  </p>
</div>

<h3>Link Loss Comparison</h3>
<table>
  <tr>
    <th>Measurement</th>
    <th>Loss (dB)</th>
    <th>Delta</th>
  </tr>
  <tr>
    <td>Baseline Fingerprint</td>
    <td>{BASELINE_LOSS} dB</td>
    <td>-</td>
  </tr>
  <tr>
    <td>Current Measurement</td>
    <td>{CURRENT_LOSS} dB</td>
    <td>{DELTA_LOSS} dB</td>
  </tr>
</table>

<h2>Failure Analysis</h2>

<h3>Failure Localization</h3>
<div class="{failure_class}">
  <p><strong>Failure Type:</strong> {FAILURE_TYPE}</p>
  <p><strong>Distance from Port:</strong> {FAILURE_DISTANCE} meters</p>
  <p><strong>Description:</strong> {FAILURE_DESCRIPTION}</p>
</div>

<h3>Root Cause Assessment</h3>
<p>{ROOT_CAUSE_ANALYSIS}</p>

<h2>Recommendations</h2>

<div class="recommendation">
  <h3>Immediate Actions</h3>
  <ol>
    <li>{ACTION_1}</li>
    <li>{ACTION_2}</li>
  </ol>
</div>

<div class="recommendation">
  <h3>Follow-up</h3>
  <ul>
    <li>{FOLLOWUP_1}</li>
    <li>{FOLLOWUP_2}</li>
  </ul>
</div>

<h2>Technical Data</h2>

<h3>Baseline Measurement</h3>
<table>
  <tr><th>Measurement ID</th><td>{BASELINE_ID}</td></tr>
  <tr><th>Timestamp</th><td>{BASELINE_TIMESTAMP}</td></tr>
  <tr><th>Type</th><td>Fingerprint</td></tr>
</table>

<h3>Current Measurement</h3>
<table>
  <tr><th>Measurement ID</th><td>{CURRENT_ID}</td></tr>
  <tr><th>Timestamp</th><td>{CURRENT_TIMESTAMP}</td></tr>
  <tr><th>Type</th><td>Fault Analysis</td></tr>
</table>

<div class="metadata">
  <p><strong>Report Generated:</strong> {GENERATION_TIMESTAMP}</p>
  <p><strong>Analysis Tool:</strong> OpenCode Fiber Engineer Agent + ALM MCP Server</p>
  <p><strong>ALM Device:</strong> ADVA FSP3000 at {ALM_URL}</p>
</div>

</body>
</html>

Critical Rules

ALWAYS

✅ Use generate_alm_diagrams custom tool for diagrams
✅ Use relative image links: <img src="./otdr_baseline_comparison.png">
✅ Specify trace_type parameter when downloading traces
✅ Include white background styling (background: white)
✅ Generate baseline (green) vs current (red) comparison
✅ Create REPORT.html in current working directory

NEVER

❌ Use Chart.js or JavaScript charting libraries
❌ Embed base64 images (reports are served via webserver)
❌ Use dark themes or fancy colors
❌ Skip diagram generation
❌ Create diagrams manually with code

Output Files

After execution, you will have:

baseline.csv - Baseline fingerprint trace data
fault.csv - Current fault analysis trace data
otdr_baseline_comparison.png - Professional OTDR diagram
REPORT.html - Complete audit report (ready to serve)

Usage Example

# From OpenCode UI or CLI
/fiber-report

# Or specify port directly
/fiber-report port 3

The skill will:

Detect active alarms or ask which port to investigate
Download baseline and current traces
Generate OTDR diagram
Create standardized HTML report
Confirm files are ready to serve

Report Hosting

Reports are designed to be served via web server:

# Serve locally for viewing
python3 -m http.server 8080

# Or use any web server
# Open: http://localhost:8080/REPORT.html

All image references use relative paths (./otdr_baseline_comparison.png) so the report is self-contained and portable.

Quality Checklist

Before completing, verify:

Diagram generated successfully (PNG exists)
Diagram shows green baseline and red current traces
Report uses white background (not dark theme)
Images linked with relative paths (not embedded)
All placeholders replaced with actual data
Status badge shows correct state (RESOLVED/ACTIVE/DEGRADED)
Recommendations are actionable and specific
Technical data includes measurement IDs and timestamps

This skill ensures 100% consistent, professional fiber optic audit reports every time.