Machinery Manual Agent

Role

The Manual Agent is the only agent called twice per investigation. In Phase 1, it casts a wide net across the 621-page PureBallast 3.1 manual to find every documented cause for the observed alarm or symptom. In Phase 2, after the IOT Manager has confirmed the most likely causes, the Manual Agent returns for a deep dive — extracting specific remediation procedures, safety warnings, spare parts, and verification steps for each confirmed cause.

Tip

Phase 1 = breadth (return everything that could possibly be relevant). Phase 2 = depth (specific procedures only for confirmed causes).

---

Dual-Phase Workflow

graph TB
    subgraph "Phase 1 — Broad Cause Search"
        direction TB
        P1A["Search Alarm List\n(p.217-241)"]
        P1B["Search Troubleshooting\n(p.271-283)"]
        P1C["Process Description\nCross-Check"]
        P1D["Broader Search\n(if results are thin)"]
        P1E["Compile ALL Causes\nUNFILTERED"]

        P1A --> P1B --> P1C --> P1D --> P1E
    end

    subgraph "IOT Manager"
        MGR["Cross-Reference &\nConfirm Causes"]
    end

    subgraph "Phase 2 — Targeted Remediation"
        direction TB
        P2A["Find Remediation\nProcedure per Cause"]
        P2B["Extract Step-by-Step\nActions"]
        P2C["Extract Safety Warnings\nVERBATIM"]
        P2D["Note Tools & Spares"]
        P2E["Manual Section\nReferences"]
        P2F["Post-Remediation\nVerification Steps"]

        P2A --> P2B --> P2C --> P2D --> P2E --> P2F
    end

    P1E -->|"All possible causes"| MGR
    MGR -->|"Confirmed causes only"| P2A

    style P1A fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff
    style P1B fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff
    style P1C fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff
    style P1D fill:#0d1b2a,stroke:#1b9aaa,stroke-width:1px,color:#fff
    style P1E fill:#1a1a2e,stroke:#e94560,stroke-width:3px,color:#fff
    style MGR fill:#1a1a2e,stroke:#0f3460,stroke-width:3px,color:#fff
    style P2A fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff
    style P2B fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff
    style P2C fill:#0d1b2a,stroke:#e94560,stroke-width:2px,color:#fff
    style P2D fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff
    style P2E fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff
    style P2F fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff

---

Knowledge Sources

Source	Format	Scope
PureBallast 3.1 Manual	621 markdown pages (page_0001.md – page_0621.md)	Complete manufacturer manual — alarms, troubleshooting, procedures, technical data
Keyword Index	keywords.json	Pre-built index mapping terms to page numbers for fast lookups
Master Index	master.json	Structured table of contents with section headings and page ranges
Maritime Document Collections	22 indexed collections	Supplementary maritime regulations, class society guidelines, and technical bulletins

---

Key Manual Sections

Section	Pages	Content
Alarm List	p.217 – p.241	Every alarm code, description, possible cause, and initial action
Troubleshooting	p.271 – p.283	Symptom-based troubleshooting trees with decision paths
Process Descriptions	Various	How each subsystem works — UV treatment, filtration, CIP, dosing
CIP Procedures	p.161 – p.163	Clean-In-Place cycle steps, chemical concentrations, timing
Technical Data	p.285 – p.293	Rated values, thresholds, tolerances, and specifications

---

Phase 1 Process — Broad Cause Search

1. Search Alarm List

   Look up the specific alarm code in the alarm list (p.217–241). Extract all documented causes, descriptions, and initial actions listed for that alarm. If the alert is symptom-based rather than alarm-code-based, search by symptom description.

2. Search Troubleshooting

   Search the troubleshooting section (p.271–283) for the same alarm or symptom. Troubleshooting trees often list additional causes not covered in the alarm list, including secondary and cascading failure modes.

3. Process Description Cross-Check

   Read the process description for the affected subsystem to understand normal operating behaviour. Compare the documented normal state against the reported anomaly to identify any causes implied by the process description but not explicitly listed in alarm or troubleshooting sections.

4. Broader Search (If Thin)

   If the results from the first three steps yield fewer than two possible causes, expand the search across the full 621-page manual and the 22 indexed maritime document collections. Use keyword index lookups and broader term matching to catch edge cases.

5. Compile ALL Causes — UNFILTERED

   Return every possible cause found, regardless of perceived likelihood. Do not rank, filter, or exclude any cause at this stage. The IOT Manager performs the cross-referencing and confidence scoring — the Manual Agent’s job is completeness.

Note

Phase 1 is intentionally exhaustive. Returning a “probably irrelevant” cause is always better than omitting one that turns out to be the root cause. Let the IOT Manager decide what to discard.

---

Phase 2 Process — Targeted Remediation

1. Find Remediation Procedure

   For each confirmed cause received from the IOT Manager, locate the specific remediation procedure in the manual. Search alarm actions, troubleshooting resolutions, and maintenance procedures sections.

2. Extract Step-by-Step Actions

   Copy the complete step-by-step remediation procedure from the manual. Preserve the original ordering, numbering, and any conditional branches (e.g., “if pressure remains high after step 3, proceed to step 7”).

3. Extract Safety Warnings — VERBATIM

   Locate every safety warning, caution, and danger notice associated with the remediation procedure. Copy these exactly as written in the manual — including formatting, emphasis, and reference codes.

4. Note Tools and Spares

   List all tools, spare parts, consumables, and special equipment mentioned in the procedure. Include part numbers and specifications where documented.

5. Manual Section References

   Record the exact page numbers, section headings, and figure references for every piece of information extracted. These references allow the crew to verify and follow along in their own copy of the manual.

6. Post-Remediation Verification

   Extract the documented verification steps — how to confirm the remediation was successful. This includes expected sensor readings after repair, test procedures, and any mandatory wait times before returning to normal operation.

Safety warnings must be quoted VERBATIM — never paraphrase

Maritime safety warnings carry legal and compliance weight. Altering wording, simplifying instructions, or omitting qualifiers can create liability and endanger crew safety. If the manual says “DANGER: Disconnect power supply before opening the UV chamber. Risk of severe eye and skin burns from UV-C radiation,” that exact text must appear in the output.

---

Search Technique

The Manual Agent uses the keyword index for fast, targeted lookups before falling back to broader page reads.

# Step 1: Find matching pages via keyword index
search-indexed-documents --query "UV intensity low alarm"

# Step 2: Read the specific pages returned
cat page_0217.md  # Alarm list entry
cat page_0271.md  # Troubleshooting section

# Step 3: If keyword search is thin, broaden
search-indexed-documents --query "UV lamp" --collection "pureballast-manual"
search-indexed-documents --query "UV intensity" --collection "maritime-regulations"

---

Tools

Tool	Purpose
search-indexed-documents	Skill that searches across the 22 indexed maritime document collections and the PureBallast manual using keyword matching and semantic search
Direct File Read	Read specific markdown pages (page_0001.md – page_0621.md) when the exact page number is known from the keyword or master index
Keyword Index (keywords.json)	Pre-built lookup table mapping search terms to page numbers for fast navigation
Master Index (master.json)	Structured table of contents for section-level navigation

Note

The search-indexed-documents skill is the primary entry point. Direct file reads are used as a follow-up when a specific page needs to be read in full, or when the keyword index returns a page number that needs to be examined in context.

---

What It Does NOT Do

No Data Analysis

Never queries sensor databases, never analyses trends, never interprets telemetry values. Sensor data analysis is the Data Analysis Agent’s responsibility.

No Maintenance Checks

Never looks up maintenance schedules, work order history, or service records. Maintenance data belongs to the PMS Agent.

No Report Sending

Never generates client-facing reports, never sends emails, never formats HTML. Report creation and distribution is the Report Agent’s job.