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: ```json { "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