observe

/observe — Targeted Pattern Analysis

Run a focused observation session on a specific domain, file pattern, or question. Unlike /learn which broadly scans recent work, /observe lets you zoom in on a specific area.

When to Use

• When you want to understand how a specific pattern is used across the codebase
• When you suspect an inconsistency and want data
• When onboarding to a new area of the code
• When you want to document "how we do X here"

Execution Flow

Step 1: Determine Focus

If the user provides a focus topic, use it. Otherwise ask:

What should I observe? Examples:
  - "error handling" — how errors are wrapped, propagated, and reported
  - "test patterns" — how tests are structured and organized
  - "naming conventions" — variable, function, and file naming
  - "src/api/**" — patterns in a specific directory
  - "imports" — how dependencies are organized

Step 2: Gather Evidence

Based on the focus, run targeted analysis:

For code pattern focus:

1. Search for relevant code patterns using grep/glob
2. Sample 10-20 representative files
3. Look for consistency and deviations
4. Check git blame for when patterns were established

For directory focus:

1. List all files in the target path
2. Analyze file organization and naming
3. Read representative files for patterns
4. Check for README or documentation

For workflow focus:

1. Read .atv/observations.jsonl for relevant tool use
2. Check git log for commit patterns
3. Look at CI/CD configuration
4. Check for scripts or Makefiles

Step 3: Analyze Findings

For each observation, evaluate:

Question	Why
Is this pattern consistent?	Consistency = high confidence instinct
How many files follow it?	Volume = evidence strength
Are there deviations?	Deviations = either evolution or mistakes
When was it established?	Age = stability indicator
Is it documented anywhere?	Documentation = intentional choice

Step 4: Record Results

Append findings to .atv/observations.jsonl with a special observation type:

{
  "ts": "2026-04-06T10:30:00Z",
  "hook": "manual-observe",
  "focus": "error handling",
  "findings": [
    "All errors wrapped with fmt.Errorf %w in 18/20 files",
    "Two files use bare error returns (legacy code from 2024)",
    "Custom error types in pkg/errors/ for domain errors",
    "No panic() usage found — errors always returned"
  ],
  "suggested_instincts": [
    {
      "id": "always-wrap-errors",
      "trigger": "when returning an error from a function",
      "behavior": "wrap with fmt.Errorf using %w verb"
    }
  ]
}

Step 5: Report

Observation: [focus topic]

Findings:
  1. [Pattern] — found in N/M files examined (X% consistent)
  2. [Pattern] — found in N/M files examined (X% consistent)
  3. [Deviation] — N files deviate from the dominant pattern

Suggested instincts (run /learn to formalize):
  + [instinct-id] — "[behavior]" (evidence: N files)
  + [instinct-id] — "[behavior]" (evidence: N files)

Existing instincts affected:
  ↑ [instinct-id] — additional evidence found (+N observations)
  ? [instinct-id] — contradictory evidence found (N deviations)

Next steps:
  - Run /learn to incorporate these findings into instincts
  - Run /observe "[related topic]" to dig deeper
  - Review deviations — they may be intentional or need fixing

Quick Observations

For rapid pattern checks without full analysis:

/observe --quick "how do we handle auth?"

Quick mode:

1. Searches for relevant files (auth, middleware, session, token)
2. Reads the most relevant 3-5 files
3. Summarizes the pattern in 3-5 bullet points
4. Does NOT write to observations.jsonl

Notes

• Observations are raw data — run /learn to turn them into instincts
• Manual observations have higher signal than automatic hook observations
• The manual-observe hook type in observations.jsonl lets /learn weight these higher
• Observations are additive — run multiple times on different topics