browser-state-debug-cookbook

A practical repository for reusable debugging guidance around browser-state scraping failures.

This repo is for situations where:

• a page looks loaded
• the state path seems to exist
• but extracted business data is empty, null, or misleading
• or different command paths appear to resolve different session/state views

Focus

The goal is to make hard-won debugging lessons easier to reuse across humans and agents.

Core themes include:

• window.__INITIAL_STATE__-style scraping failures
• hydration / timing races
• command-path vs normal-path divergence
• state exists but business data is not ready
• discriminating probes vs speculative patching

Current contents

• docs/playbooks/browser-state-debug-checklist-v1.md
• docs/playbooks/browser-state-scraping-debug-policy-v1.md
• docs/playbooks/debug-cookbook-timing-race-and-state-scraping-v1.md
• docs/cases/xhs-mcp-2026-03-06.md
• templates/debug-report-template.md

Suggested reading order

1. docs/README.md
2. docs/playbooks/browser-state-debug-checklist-v1.md
3. docs/playbooks/browser-state-scraping-debug-policy-v1.md
4. docs/playbooks/debug-cookbook-timing-race-and-state-scraping-v1.md
5. docs/cases/xhs-mcp-2026-03-06.md

Current status

This repo is in pre-publication shaping. It already contains migrated seed materials, but it is still being organized for cleaner public release.

What this repo is not

This is not meant to be a rigid doctrine built from a single case. It is intended to be:

• heuristic-oriented
• extensible
• willing to weaken or remove suggestions when later evidence disagrees

Intended use

Use this repo to:

• shorten diagnosis time
• improve probe quality
• reduce patch roulette
• capture reusable debugging patterns in a shareable form

Immediate next publish-prep priorities

• expand case studies
• add issue/repro templates
• polish public-facing navigation
• decide whether a distributable skill should live in this repo or adjacent to it