moos-alog-analysis

name	moos-alog-analysis
description	Analyze existing MOOS .alog files to reconstruct missions, debug incidents, inspect helm context, or extract timestamped evidence with aloggrep, aloghelm, alogscan, and compact variable discovery.

MOOS ALog Analysis

Overview

Use this skill for two jobs:

• reconstruct what happened in a mission
• investigate suspicious event(s) in a mission

Shell Assumption

Run aloggrep, aloghelm, and alogscan directly in the current agent shell.

Do not wrap alog* commands in an extra shell bootstrap step.

Source of Truth

Analyze only the original .alog files.

Never read or rely on derived artifacts such as:

• *_alvtmp/
• *.klog
• any other files generated by alogview or similar viewers

These files are not source evidence for mission analysis. If they exist, ignore them and continue using the .alog files only.

Workflow

1. Find the relevant .alog files.
2. If you already know the variable, signal, or specific variable set you care about, go straight to targeted aloggrep queries.
3. If you need mission phases, behavior transitions, or helm context, use aloghelm.
4. If you need variable discovery, use scripts/alogvars.sh <alog_path> first. Add one or more prefixes when you already know the variable family.
5. Read raw log lines only when you need the exact posting format, need to resolve source ambiguity, or need to cite original evidence lines.
6. If the question is geometric or numeric, extract the relevant variables and analyze them directly.

Tool Policy

Autonomous tools:

• aloggrep
• aloghelm
• alogscan
• scripts/alogvars.sh

Use them with this bias:

• aloggrep is the default tool when you already know the variable names or have already narrowed the problem to a specific variable set.
• aloghelm is the default mission-context tool.
• scripts/alogvars.sh is the default discovery tool when the variable names are still unknown.
• Raw alogscan --sort=vars --nocolors is acceptable for a full variable inventory when you actually need counts, sources, or full scan metadata, but prefer scripts/alogvars.sh for compact unknown-variable discovery.

Read references/alog-tool-guide.md when you need concise examples for aloggrep, aloghelm, or alogvars.sh.

Mission Overview

For mission reconstruction:

• if the key variables are already known, use aloggrep immediately
• if the question names a specific variable set, stay targeted and use one or more aloggrep queries for that set before doing broader discovery
• use aloghelm first for modes and behaviors when mission phases matter
• use scripts/alogvars.sh only when the variable set is still unclear
• inspect raw log lines only when the exact payload format or source matters

Incident Forensics

For one event or anomaly:

• identify the relevant variables to the event
• if the user already gave a variable set, start with that set and use aloggrep directly
• if the variable names are still unknown, use scripts/alogvars.sh to discover them compactly
• use aloggrep once the variables are known
• use aloghelm if the incident may be explained by a mode or behavior change
• use shell or Python for custom logic
• use raw log lines only when you need exact evidence or payload structure
• for source attribution, prefer aloggrep <alog> <var> --format=time:var:src when the installed build emits all requested fields. Some builds advertise that format but emit only the source field; in that case use a narrow raw .alog check for timestamped source evidence instead of broad log reads.

If the question is about loops, turns, divergence, rendezvous, stops, or similar geometry, do not expect an alog* command to answer it directly. For these cases, still extract evidence only from the .alog file.

Evidence Standard

• Cite exact command(s) used.
• Cite timestamped output lines for each conclusion.

Reference

Use references/alog-tool-guide.md only if more detail is needed.