`skills/parser-break-triage/SKILL.md`

68 lines
---
name: parser-break-triage
description: Diagnoses DOM/parser failures and proposes safe selector updates. Use when a collector starts failing, HTML structure changes, or parser success rate drops.
disable-model-invocation: true
---
You are diagnosing and fixing a broken parser in the Omega Watches 2.0 price tracking system.

## Context
Each data source has versioned parsers stored in the `parser_version` table. When a source's HTML structure changes, the parser breaks and records start failing or being quarantined.

Database: PostgreSQL `omega_watches_v2`
Project: /root/Projects/omega-watches-2

## Given Information
- Failing URL(s) and source name
- Last known-good HTML snapshot hash (from `raw_snapshot` table)
- Current HTML snapshot (new page structure)
- Failing parser logs (from `collector_run` table, error_message field)

## Diagnostic Steps

### 1. Identify Break Point
- Compare old vs new HTML snapshots
- Find which CSS selectors / XPaths no longer match
- Determine if the change is structural (major) or cosmetic (minor)
- Check if the change affects all pages or specific listing types

### 2. Propose Selector Updates
- Write minimal selector changes that fix the parse
- Prefer resilient selectors (data attributes > class names > tag hierarchies)
- Test new selectors against both old and new HTML snapshots
- Document which fields are affected

### 3. Version the Parser
```sql
-- Mark old parser as not current
UPDATE parser_version SET is_current = false
WHERE source_id = (SELECT id FROM data_source WHERE name = '{source}') AND is_current = true;

-- Insert new parser version
INSERT INTO parser_version (source_id, version, selectors_json, dom_hash, is_current, notes)
VALUES (
  (SELECT id FROM data_source WHERE name = '{source}'),
  '{new_version}',
  '{new_selectors_json}',
  '{new_dom_hash}',
  true,
  'Fix for HTML change on {date}: {description}'
);
```

### 4. Create Regression Tests
- Save new HTML snapshot as fixture
- Write test that validates extraction against both old and new fixtures
- Ensure backward compatibility where possible

### 5. Rollout Plan
1. **Canary**: Run new parser against 5-10 sample URLs
2. **Compare**: Verify extracted fields match expected values
3. **Monitor**: Watch quarantine rate for 1 hour after deployment
4. **Rollback**: If quarantine rate exceeds 20%, revert to previous parser version

## Output
- Updated `collectors/{source}/parser.mjs` with new selectors
- New fixture files in `collectors/{source}/fixtures/`
- SQL migration for new parser_version
- Rollout checklist with monitoring thresholds