observe

Intent

Observe and report the current state of a specified target without modifying it. This is the foundation for situational awareness and state modeling.

Success criteria:

• Current state accurately captured with timestamp
• Relevant aspects of the target documented
• At least one evidence anchor per observation
• Uncertainty explicitly noted where state is ambiguous

Compatible schemas:

• schemas/output_schema.yaml

Inputs

Parameter	Required	Type	Description
target	Yes	string	What to observe (file path, URL, process, system)
aspects	No	array[string]	Specific aspects to focus on (e.g., ["status", "errors", "metrics"])
depth	No	string	Observation depth: surface, detailed, exhaustive

Procedure

1. Identify observation target: Clarify exactly what system, process, or entity to observe

   • Validate target is accessible and observable
   • Determine appropriate observation method (read file, query API, check process)

2. Select observation aspects: Determine what properties/attributes to capture

   • If aspects not specified, observe: status, configuration, recent changes, anomalies
   • Prioritize aspects relevant to apparent context or goal

3. Capture current state: Execute observation without modifying target

   • Use Read for file-based targets
   • Use Bash for process/system state (ps, systemctl status, etc.)
   • Record timestamp of observation

4. Document observations: Structure findings with evidence

   • Note what was observed and when
   • Highlight notable conditions or anomalies
   • Record uncertainty where state is unclear

5. Ground claims: Attach evidence anchors to all observations

   • Format: file:line for file content
   • Format: command:output for system observations

Output Contract

Return a structured object:

observation:
  target: string  # What was observed
  timestamp: string  # ISO 8601 timestamp
  status: string  # Overall status assessment
  aspects:
    - aspect: string  # Name of observed aspect
      value: any  # Observed value or state
      notable: boolean  # Whether this is noteworthy
  anomalies: array[string]  # Unexpected findings
confidence: 0..1  # Based on observation quality
evidence_anchors: ["file:line", "command:output"]
assumptions: []  # What was assumed about the target
next_actions: array[string]  # 0-3 suggested follow-ups