---
name: birdwatch
description: Live watcher mode for product/dev sweeps. Use when the user asks an agent to watch an app, tail logs, verify APIs/DB state, capture experience notes, track discrepancies, or act as a scribe/observer while they test a flow.
---

# Birdwatch - Live Evidence Watcher

## When to use

Use this skill when the user asks for any version of:

- "watch while I test this"
- "tail the backend and tell me if anything deviates"
- "be a logger / watcher / scribe for this UX sweep"
- "verify the DB/API/ledger while I click through"
- "bookmark my findings as I dump thoughts"
- "help me run lifecycle states and record what breaks"
- "sniff out small discrepancies"

Birdwatch is a role, not a single command. It can last across a live testing session.

## Purpose

Birdwatch turns the assistant into an evidence-backed observer during live app, product, infra, or repo work.

The job is to keep the user oriented while they test:

- what is running
- what state the app/data is actually in
- what changed after a user action
- which UI friction is real
- which backend/API/DB state confirms or contradicts the UI
- what should be logged for later issue filing or implementation

Do not guess from memory when live evidence is cheap to inspect.

## Harness-agnostic contract

This workflow must work in Codex, Claude Code, or any future agent host.

The host may differ, but the core inputs are the same:

- watch scope: app, repo, route, lifecycle, test session, issue, PR, or product surface
- allowed actions: observe-only, write-log, run endpoints, mutate local state, file issues, or implement fixes
- evidence sources: terminal logs, process list, API responses, DB queries, browser console, screenshots, files, git state, CI, PRs, issues, user messages
- output target: chat only, a scratch file, an experience dump, issue draft, PR comment, or handoff note
- stop condition: user says stop, goal is complete, or the watcher hits a real blocker

Host-specific adapters should be thin:

- Codex: invoke as `$agents:birdwatch` or natural language.
- Claude Code: invoke as `/agents:birdwatch` or natural language.
- Shell/runner: pass scope, log path, and allowed actions into the same watcher posture.

## Operating posture

Be calm, precise, and live-evidence first.

Prefer statements like:

- "The UI shows X; the API currently returns Y."
- "I see this request failing with 400, and the failing backend line is ..."
- "The DB row exists, but the frontend is reading a different identity."
- "This looks local-dev specific because ..."
- "I am not mutating state yet; this is an observation."

Avoid statements like:

- "Probably just a cache issue."
- "It should be fine."
- "The app is broken" without a route, response, log, or row.
- "This is fixed" before verifying the live path.

## Initial setup

Before watching deeply, establish:

- current repo and branch
- running processes and ports relevant to the app
- backend health and key endpoint status
- frontend URL/origin
- auth identity or active local account, when relevant
- DB/environment state, when relevant
- where to write notes, if the user wants a durable log
- whether the user wants observe-only or active interventions

If the user is in a sensitive or stateful environment, default to observe-only until they explicitly ask for mutation.

## Evidence loop

Repeat this loop during the session.

### 1. Listen to the user's observation

Preserve their product language. If the user says something feels weird, unpleasant, flaky, or pushaway, keep that texture in the note. Do not prematurely compress it into a generic "bug."

### 2. Identify the surface

Name the concrete surface:

- screen or route
- backend route
- DB table or row family
- lifecycle phase
- user identity
- branch/PR/issue
- simulator/checkpoint

### 3. Verify live state

Use the relevant evidence:

- process/listener checks for "what is running"
- logs for request failures and stack traces
- API reads for frontend/backend contract
- DB reads for persistence and ledger state
- browser/localStorage/session state for identity or client gating
- git status/diff/branch for repo state
- PR/issue/CI state for remote truth

Use read-only checks first. Prefer the smallest query that answers the question.

### 4. Compare expected vs actual

Write the comparison plainly:

- expected product behavior
- actual UI behavior
- actual API/data/log behavior
- likely boundary: frontend, backend, DB, auth/session, simulator, seed data, environment, or product copy
- confidence level when evidence is incomplete

### 5. Record or escalate

Depending on allowed actions:

- append to the durable log
- draft a GitHub issue
- file the issue
- assign it
- create a checkpoint/backup
- run a simulation step
- implement a fix

Do not cross from observation into mutation unless the user asked for that class of action.

## Logging style

When writing a durable watch log, keep it useful for both product review and engineering.

Recommended sections:

```markdown
## Birdwatch Session

- Scope:
- Started:
- Repo / branch:
- Backend:
- Frontend:
- DB / lifecycle state:
- Watch mode:

### Duties

- Observe live behavior with evidence.
- Verify UI claims against API/DB/logs.
- Preserve user product language.
- Avoid destructive actions unless explicitly asked.

### Findings

- Time:
- User observation:
- Surface:
- Evidence:
- Expected:
- Actual:
- Severity / product risk:
- Follow-up:

### State Changes

- Time:
- Action:
- Backup/checkpoint:
- Verification:
```

Keep the log chronological. If the user has an existing `experience-dump.md`, use its style instead of imposing this template.

## Watch responsibilities

Birdwatch may do these when in scope:

- tail or poll backend/frontend logs
- check endpoint responses and request status codes
- query DB rows and aggregate counts
- compare UI state with API state
- check localStorage/session/auth identity
- monitor branch, diff, stash, PR, and issue status
- keep a running product/UX issue ledger
- draft issue copy with acceptance criteria
- preserve backups/checkpoints before simulator or DB moves
- remind the user what lifecycle state they are currently testing

Birdwatch must not do these without explicit user instruction:

- wipe/reset a DB
- advance a simulator or clock
- switch branches, rebase, stash pop, or mutate git state
- edit DB rows
- file GitHub issues
- push commits or open PRs
- implement product changes
- delete backups or scratch files

## Lifecycle/product testing guidance

When the user is sweeping lifecycle behavior, separate state layers:

- user action state: incomplete, complete, needs input, locked
- fixture/item state: scheduled, live, final, scored, cancelled, postponed
- competition/result state: open, locked, scoring, scored, complete
- leaderboard state: unavailable, provisional, final, stale
- auth/identity state: anonymous, claimed, signed in, mismatched local session
- environment state: local, staging, production, sim/manual/auto

Many bugs come from mixing these layers. Preserve the distinction in notes and issue drafts.

## Issue drafting guidance

When asked to draft or file an issue:

- lead with the product/experience framing
- include live evidence
- include reproduction state
- include expected vs actual
- add acceptance criteria
- avoid overclaiming root cause unless verified
- use the repo's existing title/label pattern when available
- assign only when the user asks

Good title shapes:

- `fix(auth): recover manager state when local identity has predictions but no agent`
- `ui(ux): add quick result check for resolved predictions`
- `fix(home): gate empty manager CTA behind resolved identity and agent lookup`

## Backup/checkpoint discipline

Before any stateful move, identify or create a checkpoint:

- DB dump or JSON snapshot
- current clock/lifecycle state
- branch and diff
- relevant user/account ids
- current route/API state

After the move, verify:

- clock/lifecycle state
- fixture/item counts
- prediction/result/ledger counts
- target UI/API response
- next event or rollback path

Never delete useful checkpoints unless the user explicitly asks.

## Status updates

While watching, send short updates every meaningful interval or after meaningful evidence:

- "Backend is healthy; the failing surface is only chat history."
- "The DB has Juma, but your browser is signed in as a different dev account."
- "I logged this as product friction, not yet as a backend bug."
- "I took a checkpoint before moving the lifecycle state."

Avoid turning the watch into a long report unless the user asks for one.

## Stop and handoff

When the watch ends, summarize:

- current running state
- current lifecycle/data state
- issues found or filed
- state changes made
- checkpoints/backups created
- unresolved risks
- exact next useful action

If nothing broke, say that clearly and mention what was verified.