kiyoraka/project-ai-memorycore/observation-system

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