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

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

Field Definitions

Examples

Example 1: Observe Process Status

Input:

target: "web-server process"
aspects: ["running", "memory", "connections"]

Output:

observation:
  target: "nginx process (PID 1234)"
  timestamp: "2024-01-15T10:30:00Z"
  status: "healthy"
  aspects:
    - aspect: "running"
      value: true
      notable: false
    - aspect: "memory"
      value: "125MB RSS"
      notable: false
    - aspect: "connections"
      value: 847
      notable: true
  anomalies:
    - "Connection count higher than typical (avg: 200)"
confidence: 0.95
evidence_anchors:
  - "command:ps aux | grep nginx"
  - "command:netstat -an | grep :80"
assumptions:
  - "Process identified by name 'nginx'"
next_actions:
  - "Monitor connection trend over time"
  - "Check for connection leak if count continues rising"

Example 2: Observe File State

Input:

target: "config/database.yml"
aspects: ["content", "permissions", "modified"]

Output:

observation:
  target: "config/database.yml"
  timestamp: "2024-01-15T10:35:00Z"
  status: "present"
  aspects:
    - aspect: "content"
      value: "PostgreSQL configuration with production credentials"
      notable: true
    - aspect: "permissions"
      value: "644"
      notable: true
    - aspect: "modified"
      value: "2024-01-14T15:22:00Z"
      notable: false
  anomalies:
    - "File permissions allow group/other read (sensitive credentials)"
confidence: 0.9
evidence_anchors:
  - "config/database.yml:1-25"
  - "command:ls -la config/database.yml"
assumptions:
  - "File contains database credentials based on content inspection"
next_actions:
  - "Review file permissions for security"
  - "Consider using environment variables for credentials"

Verification

• • Observation timestamp is current (within observation window)
• • At least one aspect was observed and documented
• • Evidence anchors exist for each notable observation
• • Target was not modified during observation
• • Anomalies are supported by evidence

Verification tools: Read (to verify file observations)

Safety Constraints

• •mutation: false
• •requires_checkpoint: false
• •requires_approval: false
• •risk: low

Capability-specific rules:

• •NEVER modify the target during observation
• •Do not access targets outside authorized scope
• •Report access failures rather than attempting workarounds
• •Note uncertainty when observations may be stale or incomplete

Composition Patterns

Commonly follows:

• •search - Observe specific targets found through search
• •retrieve - Observe content retrieved by reference

Commonly precedes:

• •state - Observations feed into world state modeling
• •detect - Observations provide data for pattern detection
• •compare - Observations enable comparison with expected state

Anti-patterns:

• •Never use observe for modification (use mutate)
• •Avoid observe for pattern matching (use detect)

Workflow references:

• •See reference/workflow_catalog.yaml#debug_code_change for observation in debugging
• •See reference/workflow_catalog.yaml#world_model_build for observation in modeling