---
name: observe-first
description: Enforce read-map-understand before any edit. Use at the start of any workflow that modifies existing code in an unfamiliar or partially-familiar codebase. Prevents the "Junior Refactor" failure mode — making changes without knowing what the code does or how it's used. Side-chain skill that gates the modify phase.
user-invocable: false
model-invocable: true
side-effects: file-writes
permission-profile: normal
triggers:
  - build
  - repair
  - review
  - "*"
---

# Observe First

## Iron Law

```
NO EDIT WITHOUT A MENTAL MODEL.
NO MENTAL MODEL WITHOUT EVIDENCE.
```

If you have not completed Phase 1 (Structure) and Phase 2 (Usage), you are not permitted to modify any file. The modification phase is blocked until both phases produce written findings.

## Recognize Your Own Rationalizations

These are the exact shortcuts you will reach for. Each is wrong:

- "I can see what it does from the name." → Names lie. Read the body.
- "I only need to change one line." → You don't know which one yet without reading the callers.
- "I've seen this pattern before." → Familiarity is not analysis. This codebase may use the pattern differently.
- "I'll figure it out as I go." → Going is the wrong order. Understand first, then go.
- "The tests will catch mistakes." → Tests catch regressions you knew about. They don't catch structural misunderstandings.

## When to Run

- Any workflow that modifies existing code you haven't read end-to-end in this session.
- Planning phases that require accurate impact analysis before choosing an approach.
- Whenever the scope of a change is unclear.

Do NOT skip this skill for "small" changes — small changes with wrong mental models cause the most silent bugs.

## Skill Chain

Side-chain gate. Blocks the modify phase until both observe phases complete.

```
← prev:  plan, spec-first-tdd, or any workflow beginning a modify phase
→ next:  return to the invoking workflow once Phase 1 + Phase 2 are in writing
```

## Phase 1 — Structure Map

Map the file/module being modified before touching it.

```bash
# Who owns the symbol?
rg -n "export.*<symbol>|function <symbol>|class <symbol>" src/ packages/

# What does the file do?
cat <file> | head -80           # module header, imports, exports
rg -n "export " <file>          # public surface

# What are its dependencies?
rg -n "^import " <file>         # what it imports
rg -rn "from.*<module>" src/    # who imports this module
```

Produce written output:
1. **Module purpose** — one sentence: why does this module exist?
2. **Exports** — list every exported symbol and its type
3. **Callers** — list every file that imports this module
4. **Dependencies** — list what this module imports from elsewhere

Do NOT proceed to Phase 2 until this list exists in writing.

## Phase 2 — Usage Analysis

For each symbol you intend to modify, trace how it is called.

```bash
# All call sites
rg -n "<symbol>" src/ packages/ --type ts --type js

# Test coverage
rg -rn "<symbol>" src/ --include="*.test.*"

# Recent history
git log --oneline -10 -- <file>
git log --oneline -10 -S "<symbol>"    # commits that changed this symbol
```

Produce written output for each symbol:
1. **Call sites** — file:line for every caller, with the argument values passed
2. **Contract** — what callers expect in return (inferred from usage)
3. **Invariants** — what must be true before/after this symbol runs
4. **Change blast radius** — which callers break if you change the signature or behaviour

Do NOT write any code until this list exists in writing.

## Phase 3 — Modification (Unblocked)

Only after Phases 1 and 2 are documented:

1. Make the **smallest** change that satisfies the contract.
2. Keep changes inside the blast radius you mapped — no scope creep.
3. If the blast radius is larger than expected, surface it before continuing.
4. Update callers in the order dictated by the dependency map, not alphabetically.

## Completion Criteria

You may exit this skill and return to the invoking workflow when:

- [ ] Phase 1 findings written (module purpose, exports, callers, deps)
- [ ] Phase 2 findings written (call sites, contract, invariants, blast radius) for every symbol to be modified
- [ ] The modification is bounded to the mapped blast radius

If Phase 1 or Phase 2 reveals that the change is larger than originally scoped, **stop and surface the new scope** before modifying anything.
