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