Observation

Observation System — Tiered Code Awareness

"See clearly before you act. Act only on what you see."

Activation

Four commands, each at a different depth:

Then execute the matching protocol below.

Context Guard

Protocol

Step 1: Determine Command

Parse the user's request and dispatch to the matching depth level:

Step 2: Execute Tier Protocol

Follow the detailed protocol for the selected command (see sections below).

Step 3: Suggest Escalation

After completing any tier, suggest the next appropriate depth if findings warrant it (see Escalation Paths).

Depth Levels

Four commands at three depth levels. Survey/Investigate/Audit are investigative (observe and report). Refine is corrective (observe and fix).

When to Use Which

Escalation Paths

Survey spots problem area    → Investigate that area
Investigate finds deep issue → Audit the full system
Survey/Investigate/Audit     → Refine specific code
Refine finds systemic issue  → Audit the full system

Lv.1: Survey

Quick bird's-eye view of a project — structure, tech stack, health, and recent activity.

Arguments

Step 1: Dependency Scan

Adapt to the project's actual stack:

• Frontend: Read package manifest (package.json, pubspec.yaml, etc.) — UI library, framework, test runner
• Frontend: Scan component directories — check for custom wrappers that override standard behavior
• Backend: Read project file (.csproj, pom.xml, go.mod, Cargo.toml, etc.) — dependencies, framework version
• Skip if project type doesn't apply (backend-only, frontend-only)

Step 2: Structure Scan

• Count files by type (backend, frontend, test, config)
• Identify architecture pattern (Clean Architecture, N-Tier, monolith, etc.)
• Note project organization (monorepo, multi-project, single app)

Step 3: Tech Stack Detection

Detect from project files:

• .csproj → .NET version, target framework
• package.json → Frontend framework, key dependencies
• Database provider (from config or ORM setup)
• CI/CD pipeline (.github/workflows/, Jenkinsfile, etc.)
• Container setup (docker-compose.yml, Dockerfile)

Step 4: Health Check

• Build status — any errors? (dotnet build / npm run build)
• Git status — uncommitted changes? (git status --short)
• Branch status — ahead/behind remote?
• Last commit date — how stale?
• TODO/FIXME/HACK count — outstanding markers

Step 5: Recent Activity

• Show last 5 commits (git log --oneline -5)
• Note active branch and any open work

Step 6: Domain Lesson Check

Cross-reference project against past incidents (if Post-Mortem System is installed):

• Scan post-mortem records for entries matching this project's domain
• Show max 3 most relevant lessons
• If same failure type appears 2+ times: flag as recurring
• Skip section entirely if no matches found

Survey Output Format

Survey: [PROJECT NAME]

Structure: [X] backend | [Y] frontend | [Z] tests
Stack:     [.NET X] + [Framework] + [DB]
Health:    [Build status] | [Git status] | [Last commit]
Recent:    [Last 3-5 commits, one line each]
Lessons:   [N relevant past incidents] (if any)

Deeper analysis? → investigate <area>
Full audit?      → audit

Keep it compact — the whole output should fit on one screen.

Survey All

When all is specified, scan all active projects and show a summary table:

Survey: All Active Projects

#1 ProjectA  — .NET 10 + Nuxt 3  | Clean     | 2 days ago
#2 ProjectB  — .NET 9 + React 19 | 3 dirty   | 3 days ago
#3 ProjectC  — Next.js 15        | Clean     | 2 weeks ago

Lv.2: Investigate

Focused investigation of a specific area — trace bugs, reveal hidden patterns, analyze code flow.

Arguments

Step 1: Dependency Scan

• Frontend: Package manifest + custom component wrappers (read actual type definitions)
• Backend: Project file + dependency injection/service registrations (e.g., Program.cs, app.module.ts, main.go)
• Never assume standard library behavior — verify against actual source

Mode A: File Analysis

• Read the target file completely
• Map dependencies (what it imports/uses)
• Map dependents (what uses this file — grep for references)
• Check pattern compliance with project conventions
• Identify issues: bugs, code smells, deviations
• Report connections to larger architecture

Investigate: AuthService.cs

Location:     src/Application/Services/AuthService.cs
Dependencies: IUserRepository, IJwtService, IRefreshTokenRepository
Used by:      AuthController.cs, MiddlewareExtensions.cs

Findings:
  1. Token expiry hardcoded (line 47) — should be from config
  2. No rate limiting on login attempts
  3. RefreshToken rotation working correctly

Hidden Pattern:
  Logout doesn't invalidate ALL refresh tokens for a user —
  only the current one. Multi-device login leaves stale tokens.

Related library entries: [jwt-refresh-token-pattern] (if Library System installed)

Mode B: Topic Investigation

• Search across all project files for related terms
• Map all files touching this topic
• Trace data/logic flow end-to-end:

Entry Point → Controller → Service → Repository → Database
     |             |           |           |           |
  [Route]    [Validation]   [Logic]    [Query]     [Table]

• Report hidden patterns and undocumented behavior

Mode C: Bug Investigation

• Parse symptom — what's failing, when, where?
• Trace backwards from symptom to root cause:

Symptom: "[description]"
    |
UI: Component → handler function
    |
API: endpoint call
    |
Backend: Controller → Service → [where it breaks]
    |
ROOT CAUSE: [specific cause with file:line]

• Provide fix options with recommendation

Mode D: Code Review

• Read the file
• Review checklist:
  • Follows project conventions (naming, structure)
  • Error handling present and appropriate
  • No hardcoded secrets or magic numbers
  • Input validation at boundaries
  • Null safety / defensive coding
  • Performance considerations
  • Test coverage exists
• Score and report findings

Investigate Output Format

Investigate: [target]

Location:  [file path or topic scope]
Files:     [N files touching this area]

Findings:
  1. [Finding with file:line reference]
  2. [Finding with file:line reference]

Hidden Patterns:
  [Non-obvious behavior or undocumented assumptions]

Related: [library entries if Library System installed]
Escalate: investigate <deeper area> | audit (if systemic)

Lv.2: Refine (Corrective)

Reviews changed code for reuse, quality, and efficiency — then fixes what it finds.

Key difference from other tiers: Refine doesn't just observe — it acts. After presenting findings, it fixes issues with permission.

Arguments

Step 1: Dependency Scan

• Frontend: Read package manifest + scan custom component wrappers
• Backend: Read project file + check DI/service registrations
• Never assume standard props — read actual component type definitions

Step 2: Identify Scope

Skip: Generated files, migrations, lock files, node_modules, bin/, obj/

Step 3: Read & Understand

For each file in scope:

• Read the full file — understand context, not just the diff
• Read the diff — focus on what changed
• Identify intent — what is the author trying to do?

Rule: Understand intent before judging quality. Never "fix" something that was intentional.

Step 4: Analyse (The Refinement Checklist)

Code Quality

• Dead code — unused variables, unreachable branches, commented-out blocks
• Duplication — same logic repeated (extract if 3+ occurrences)
• Naming — clear, consistent with project conventions
• Complexity — can any nested logic be simplified?

Reuse & Structure

• Existing utilities — is there already a helper for this?
• Abstraction level — too low (verbose) or too high (over-engineered)?
• Single Responsibility — does each function/class do one thing?

Efficiency

• Obvious N+1 queries or unnecessary loops
• Missing early returns that would reduce nesting
• Unnecessary allocations or copies

Project Rules Compliance

• Follows project coding rules (check CLAUDE.md or project conventions)
• API contract respected (backend naming → frontend follows)
• Date/time handling correct for the project's timezone strategy

What NOT to Flag

• Style preferences that don't affect correctness
• Missing documentation on code that wasn't changed
• Performance micro-optimizations that don't matter at scale
• "Best practices" that add complexity without value

Step 5: Report Findings

Refine: [scope]

Reviewed: [N] files, [N] lines changed

Found:
  [N] issues to fix (dead code, bugs, N+1)
  [N] suggestions (could improve, optional)
  [N] files — clean, no action needed

Details:
  [file:line] — [category] — [description]

Step 6: Fix (With Permission)

After presenting findings, always ask the user before applying any fixes:

1. Present findings with the report format above
2. Ask user: "Fix all? Fix critical only? Skip?"
3. On approval — apply the requested fixes
4. Verify — run build after fixes to confirm nothing broke
5. Report what was changed

Fix Categories

Rule: Never auto-apply fixes without user approval. Present findings first, fix second.

Lv.3: Audit

Full system audit — ALL connections, dependencies, data flows, and their consequences revealed.

Arguments

Step 1: Dependency Scan (Full)

Frontend

• Read package manifest (package.json, etc.) — UI library, state management, build tool, test framework
• Scan component directories — list all custom component wrappers
• Read key custom components' type/interface definitions
• Check compiler/bundler config (tsconfig.json, vite.config.ts, etc.) — path aliases, strictness

Backend

• Read project file (.csproj, pom.xml, go.mod, etc.) — dependencies, target framework
• Read entry point (Program.cs, main.go, app.module.ts, etc.) — DI registrations, middleware, auth scheme
• Check for custom base classes, shared constants, conventions

Step 2: Load Full Context

• Read project context files (if session tracking is configured)
• Search library/knowledge base for related entries (if Library System installed)
• Check recent session history with this project (if diary/session system is configured)

This is the only tier that loads FULL available context before analysis. Skip any context sources that are not configured.

Step 3: Architecture Map

Read the entire project structure and draw an architecture diagram:

Audit: [PROJECT] — Full System Audit

ARCHITECTURE MAP
+-----------------------------------------------+
|                    CLIENT                       |
|  [Framework] + [UI Library] + TypeScript        |
|  Pages -> State -> API calls                    |
+------------------------+----------------------+
                         | HTTP/HTTPS
+------------------------v----------------------+
|                 API LAYER                       |
|  [Backend Framework]                            |
|  Controllers -> Services                        |
+-----------------------------------------------+
|              APPLICATION LAYER                  |
|  Services, DTOs, Interfaces                     |
+-----------------------------------------------+
|               DOMAIN LAYER                      |
|  Entities, Enums, Value Objects                 |
+-----------------------------------------------+
|            PERSISTENCE LAYER                    |
|  [ORM] + [Database]                             |
+------------------------+----------------------+
                         |
              +----------v----------+
              |    [Database]       |
              +---------------------+

Step 4: Dependency Analysis

Map ALL dependencies — internal and external:

• Internal: Controller → Service → Repository → Database chain for each major module
• External: NuGet/npm packages (versions, outdated?), external APIs, infrastructure
• Implicit/Hidden: Hardcoded values, data shape assumptions, cross-table relationships not enforced by FK, environment-specific behavior

DEPENDENCY MAP

Explicit (enforced):
  EntityA -> EntityB (FK: entity_b_id)

Implicit (NOT enforced):
  ! Config dictionary hardcoded in Service — no migration
  ! String comparison for role check — not constant/enum

Step 5: Data Flow Audit

Trace ALL data flows through the system:

• For each major feature, trace: Entry Point → Processing → Storage → Output
• Identify data transformations at each step
• Flag any flows with missing validation or authorization gaps

Step 6: Risk Assessment

Categorize findings by risk level:

RISK ASSESSMENT

HIGH:
  - [Critical finding with impact]

MEDIUM:
  - [Notable finding, should address]

LOW:
  - [Minor, address when convenient]

Step 7: Recommendations

Based on full audit, provide prioritized actionable recommendations:

RECOMMENDATIONS (prioritized)

1. [HIGH] [Action item with clear rationale]
2. [MED]  [Action item]
3. [LOW]  [Action item]

Step 8: Knowledge Connections

Link findings to existing library entries (if Library System installed):

• Search library for entries related to audit findings
• Suggest library entries to reference or create
• Flag if audit reveals knowledge gaps worth documenting

Audit Cross — Cross-Project Analysis

When cross is specified, analyze shared patterns across all active projects:

Audit: Cross-Project Analysis

SHARED PATTERNS
  Auth: JWT + Refresh Token — ProjectA, ProjectB, ProjectC
  DB:   PostgreSQL — ProjectA, ProjectB
  Arch: Clean Architecture — ProjectA, ProjectB

DIVERGENCES
  Frontend: Vue (A) vs React (B) vs Next.js (C)
  Hosting:  Railway (A) vs IIS (B) vs Vercel (C)

OPPORTUNITIES
  - Auth pattern could be extracted to shared library
  - Database patterns consistent across projects

Shared: Dependency Scan Philosophy

All tiers start with a dependency scan. This is deliberate — observation skills review code against patterns. Wrong pattern assumptions lead to wrong findings and broken builds.

Rule: Never assume standard library behavior. Custom wrappers may change prop signatures, method behavior, or DI lifetimes. Always verify against actual source before suggesting changes.

Cross-Feature Integration

Library System

When the Library System is installed, observation tiers integrate with it:

• Survey: Check library for domain-related entries
• Investigate: Reference relevant library entries in findings
• Audit: Link findings to library knowledge, suggest new entries for undocumented patterns
• Refine: Check if existing utilities exist in library before suggesting new abstractions

Post-Mortem System

When the Post-Mortem System is installed:

• Survey: Cross-reference project against past post-mortem entries (domain lesson check)
• Investigate (bug mode): Check if similar bugs were documented before
• Audit: Surface recurring failure patterns across post-mortems

Work-Plan Execution

• Survey before planning → informed scope assessment
• Refine after each work-plan task → quality gate before commit
• Audit after major milestones → systemic health check

Auto-Commit System

• Refine → fixes applied → auto-commit (if installed)

Cost Awareness

Not all tiers require the same computational effort. Matching tier to model saves cost without sacrificing quality.

Practical Guidelines

• Survey can run as a background agent or lighter model — it's mostly file scanning and git commands
• Investigate and Refine benefit from the primary AI's reasoning — pattern matching, intent understanding, and judgment calls
• Audit is the most expensive tier — reserve for milestone reviews, not daily checks
• Survey is cheap to run often — low cost and catches problems early. Consider running before every planning session.
• Refine before every commit — medium cost but prevents expensive bugs from shipping

Cost-Saving Pattern

Daily workflow:
  Survey (low)  → code → Refine (medium) → commit
                         ^-- catches issues before they compound

Weekly/milestone:
  Audit (high)  → captures systemic issues that daily Refine misses

The key insight: frequent cheap observation prevents expensive deep audits. A team that Surveys daily and Refines before every commit rarely needs emergency Audits.

Mandatory Rules

1. Always dependency scan first — never review code without understanding the project's actual stack and custom components
2. Never assume standard library behavior — read actual source, especially for UI component wrappers
3. Understand intent before judging — the author's approach may be intentional; don't "fix" what isn't broken
4. Escalate, don't skip tiers — if Survey reveals complexity, suggest Investigate or Audit; don't try to deep-dive in a Survey
5. Refine always asks permission before fixing — present findings first, apply fixes only after user approval
6. Compact output for Survey — should fit on one screen; deeper tiers can be verbose
7. Link to library when available — if Library System is installed, connect findings to existing knowledge entries; skip gracefully if not installed
8. Report format consistency — use the output templates defined in each tier for recognizable, parseable output

Edge Cases

Level History

• Lv.1 — Base: Four-tier observation system (Survey, Investigate, Refine, Audit) with escalation paths between tiers. Survey scans project health in 30 seconds. Investigate traces bugs, reviews code, and maps data flows. Refine reviews changed code and fixes issues with permission. Audit performs full system audit with architecture mapping, dependency analysis, risk assessment, and recommendations. (Origin: Developed and refined across multiple production projects)
• Lv.2 — Cross-Feature: Integration with Library System (knowledge connections), Post-Mortem System (domain lesson check), Work-Plan Execution (quality gates), and Auto-Commit System (refine-then-commit chain). Observation becomes aware of the broader skill ecosystem.