# Observe

> On-demand codebase health check. Use when "observe", "health check", "is the codebase healthy", "check for drift", "system status", or before starting a large feature.

- Skill: `majiayu000/observe-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/observe-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/observe-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/observe-3

---


# Role

OBSERVE. Assess codebase health across independent dimensions using
parallel agents. Detect architectural drift before it compounds. The
codebase itself is the baseline — dominant patterns and CLAUDE.md
conventions define healthy.

## Principles

1. **The codebase is the baseline** — Compare against what the codebase
   already establishes: dominant patterns, CLAUDE.md rules, existing
   test coverage. No external spec required.
2. **Parallel dimensions** — Each health dimension is independent.
   Agents run simultaneously. No agent needs another's output.
3. **Concrete over vague** — Every finding must cite a file, line, or
   metric. "Code quality could improve" = discard.
4. **Drift is deviation from established patterns** — If 90% of files
   use pattern X and 10% use pattern Y, the 10% is drift. Not wrong,
   but worth surfacing.
5. **Observe, don't prescribe** — Report findings. Never fix, refactor,
   or modify code. The user decides what to act on.

## Process

1. **Orient** — Read CLAUDE.md for project conventions. Scan directory
   structure for scope. Determine project type (monorepo, single app,
   library, plugin).

   If a specific scope is requested ("observe the API layer"), limit
   agents to that scope. Otherwise, assess the full project.

   Announce: `[OBSERVE] Scanning {scope} across 5 dimensions`

2. **Spawn assessors** — 5 parallel agents via Task tool.

   Each agent receives: project scope + CLAUDE.md conventions +
   dimension instructions. Each produces findings as:
   `{severity} — {file}:{line} — {finding} — {evidence}`

   digraph observe {
     rankdir=LR
     orient -> types
     orient -> patterns
     orient -> tests
     orient -> deps
     orient -> dead
     types -> health
     patterns -> health
     tests -> health
     deps -> health
     dead -> health
   }

   **Type Safety** — "How sound is the type system?"
   Task(prompt="[project scope + conventions]
   Check: `any` usage, missing return types on exports, type
   assertions (as), implicit any in function params, untyped
   dependencies. Run `tsc --noEmit` if tsconfig exists. Count
   type coverage: typed exports / total exports.
   Report findings as BLOCKER/WARNING/SUGGESTION with evidence.",
   subagent_type="general-purpose")

   **Pattern Compliance** — "Does the code follow its own conventions?"
   Task(prompt="[project scope + CLAUDE.md rules]
   Check: naming conventions, file organization, import patterns,
   error handling style (result types vs exceptions), component
   patterns. Identify the DOMINANT pattern per category, then
   flag deviations. Drift = minority pattern diverging from majority.
   Report findings with evidence.",
   subagent_type="general-purpose")

   **Test Coverage** — "What's untested?"
   Task(prompt="[project scope]
   Check: run test coverage if available. Identify critical paths
   without tests (auth, payments, data mutations). Flag test files
   that exist but are empty or have only skipped tests. Count:
   tested modules / total modules.
   Report findings with evidence.",
   subagent_type="general-purpose")

   **Dependency Health** — "Are dependencies current and clean?"
   Task(prompt="[project scope]
   Check: outdated packages (run audit if available), unused
   dependencies (imported but not used), duplicate dependencies,
   known security advisories. Compare lock file age.
   Report findings with evidence.",
   subagent_type="general-purpose")

   **Dead Code** — "What's unused?"
   Task(prompt="[project scope]
   Check: unused exports (exported but never imported), orphaned
   files (no imports pointing to them), unreachable code branches,
   commented-out code blocks, TODO/FIXME/HACK comments older than
   the surrounding code.
   Report findings with evidence.",
   subagent_type="general-purpose")

3. **Aggregate** — Collect findings from all agents. Per dimension,
   assign a status:

   | Status | Condition |
   |--------|-----------|
   | OK | No findings or SUGGESTIONs only |
   | WARNING | WARNINGs present, no BLOCKERs |
   | BLOCKER | BLOCKERs present |

   Compute health score: start at 100, subtract per finding:
   BLOCKER = -20, WARNING = -5, SUGGESTION = -1. Floor at 0.

4. **Report** — Emit health card:

   ```
   [OBSERVE] Health: {score}/100 | {date} | Scope: {scope}
   Type Safety:        {OK/WARNING/BLOCKER} — {top finding or "Clean"}
   Pattern Compliance: {OK/WARNING/BLOCKER} — {top finding or "Clean"}
   Test Coverage:      {OK/WARNING/BLOCKER} — {top finding or "Clean"}
   Dependencies:       {OK/WARNING/BLOCKER} — {top finding or "Clean"}
   Dead Code:          {OK/WARNING/BLOCKER} — {top finding or "Clean"}

   satisfaction: {score} | confidence: {high/med/low} | basis: {measurement/observation/inspection}
   ```

   Confidence: high if tools ran (type checker, test suite); med if file
   analysis only; low if sampling.

   Below the card: per dimension, list all findings grouped by severity.
   BLOCKERs include remediation hints.

   `[EXTRACT] Key insight: [one reusable finding ≤15w]`

## Boundaries

Observe assesses codebase health. It does NOT:

- Fix, refactor, or modify any code (report only)
- Replace CI/CD pipelines (complements automated checks)
- Track changes over time (each run is a snapshot)
- Compare against external standards (the codebase is the baseline)
- Assess business logic correctness (that's verify or loop)

## Handoff

Observe is standalone — returns health card to the user. No outbound
Skill() calls.

- BLOCKERs found → user decides whether to address now or track
- Can feed into shape as `PATTERNS:` context for future tasks
- Can inform bond team design (health card shows which areas need work)