# Web Matcher Filter Enablement Plan — Diagnosis

Date: 2026-04-20
Read-only diagnosis. No changes made.

---

## Disabled Filter Elements (index.html)

5 filter groups are disabled, each wrapped in `<div class="filter-group filter-disabled" title="Coming soon">`:

| Line | Filter Group | Checkboxes | Values | Default State |
|---|---|---|---|---|
| 78-84 | Energy Level | 3 | low, medium, high | All unchecked, disabled |
| 87-91 | Special Needs | 1 | yes | Unchecked, disabled |
| 94-101 | Good with Kids | 4 | unknown, yes, somewhat, no | "Unknown" checked+disabled, rest unchecked+disabled |
| 104-111 | Good with Dogs | 4 | unknown, yes, somewhat, no | "Unknown" checked+disabled, rest unchecked+disabled |
| 114-121 | Good with Cats | 4 | unknown, yes, somewhat, no | "Unknown" checked+disabled, rest unchecked+disabled |

Each compatibility filter (kids/dogs/cats) has an "Unknown" checkbox that is **checked by default**. This is critical for the UX behavior below.

---

## How Unknown Is Handled (applyFilters, app.js:311-410)

### Compatibility filters (goodWithKids, goodWithDogs, goodWithCats)

Each works identically:

```javascript
if (selectedValues.length > 0) {
  const match = animal.behaviorNotes?.[field + '_match'];
  const isUnknown = !match || match === 'unknown';
  if (isUnknown) {
    if (!selectedValues.includes('unknown')) return false;  // exclude
  } else {
    if (!selectedValues.includes(match)) return false;      // exclude
  }
}
```

**Behavior per scenario:**

| Checkboxes selected | Animal has `_match='yes'` | Animal has `_match='unknown'` | Animal has NO notes at all |
|---|---|---|---|
| None selected | ✅ Pass (filter inactive) | ✅ Pass (filter inactive) | ✅ Pass (filter inactive) |
| [yes] only | ✅ Pass | ❌ Excluded | ❌ Excluded |
| [yes, unknown] | ✅ Pass | ✅ Pass | ✅ Pass (no notes → unknown) |
| [unknown] only | ❌ Excluded | ✅ Pass | ✅ Pass |

**Key insight:** Animals with NO behavior notes at all are treated as `unknown` (because `animal.behaviorNotes?.goodWithKids_match` is `undefined`, which triggers `isUnknown = true`). The "Unknown" checkbox being pre-checked by default means **animals without profiler data are always included when filters are first enabled**.

### Energy level filter

```javascript
if (selectedEnergies.length > 0) {
  const energyMatch = animal.behaviorNotes?.energyLevel_match;
  if (!energyMatch || energyMatch === 'unknown' || !selectedEnergies.includes(energyMatch)) {
    return false;
  }
}
```

**No "Unknown" checkbox for energy.** If any energy checkbox is selected, animals with unknown/missing energy are **always excluded**. This is stricter than the compatibility filters.

### Special needs filter

Only has a "Yes" checkbox. When checked, only animals with meaningful `specialNeeds` text are shown. When unchecked, filter is inactive (all pass).

---

## Species-Aware Filter Visibility (updateFilterVisibility, app.js:119-152)

Smart UX already built: when viewing dogs, "Good with Dogs: No" and "Good with Dogs: Unknown" are hidden (nonsensical to filter dogs by whether they're good with dogs). Cross-species filters remain visible.

| Tab | Hidden elements | Shown elements |
|---|---|---|
| Dogs | goodWithDogs: No, Unknown | goodWithCats: all, goodWithKids: all |
| Cats | goodWithCats: No, Unknown | goodWithDogs: all, goodWithKids: all |
| Small | (none hidden) | All shown |

---

## Data Coverage Impact

| Metric | Count |
|---|---|
| Total animals in metadata | 378 |
| Animals with profiler notes | 19 (5%) |
| Animals without notes | 346 (95%*) |

*Note: 378 metadata - 19 with notes ≠ 346 exactly because metadata includes non-adoptable animals. The key point: 95% of animals have NO behavior notes.

### Enum value distribution (across 19 profiled animals)

| Filter | yes | somewhat | no | unknown |
|---|---|---|---|---|
| goodWithKids | 9 | 5 | 2 | 8 |
| goodWithDogs | 6 | 2 | 2 | 11 |
| goodWithCats | 10 | 3 | 2 | 7 |
| energyLevel | low:8 med:2 high:5 | — | — | 7 |

### Filter strictness scenarios

| Scenario | Animals remaining |
|---|---|
| All filters OFF (current) | All adoptable (~100+) |
| Compatibility filters ON, only "Yes" checked (strictest) | 3 animals |
| Compatibility filters ON, "Yes" + "Unknown" checked (default state) | All adoptable (unknown = ~95% pass through) |
| Energy = "Low" checked | 8 animals (all others excluded, including unknown) |

---

## Proposed Enablement Plan

### Safe to enable today

The "Unknown" checkbox being **pre-checked by default** is the safety mechanism. When filters are first enabled:
- All 346 animals without notes pass through (treated as unknown)
- Only animals with explicit "no" values get filtered out (2-3 animals per category)
- The default UX is essentially unchanged from today

### Concrete fix

**HTML changes (index.html):**
1. Remove `disabled` from all 16 checkbox `<input>` elements (lines 81-83, 90, 97-100, 107-110, 117-120)
2. Remove `filter-disabled` CSS class from the 5 `<div class="filter-group">` wrappers (lines 78, 87, 94, 104, 114)
3. Remove `title="Coming soon"` from those same 5 divs

**JS changes:** None. `applyFilters()` already handles all these filters correctly. Event listeners are already bound (app.js:69-76 loops over all filter names including the disabled ones).

**CSS changes:** Check if `.filter-disabled` has opacity/pointer-events styling. If so, removing the class is sufficient. If the styling is on `[disabled]` inputs, removing the attribute is sufficient.

### Risk assessment

| Risk | Level | Mitigation |
|---|---|---|
| Empty results when strict filters applied | Low | "Unknown" pre-checked means default = permissive |
| Energy filter too strict (no Unknown option) | Medium | Could add an "Unknown" checkbox for energy, or accept that energy filtering only works for profiled animals |
| Users confused by filter having no effect | Low | 95% of animals are unknown, so filters only differentiate the 19 profiled animals |
| Compatibility data is wrong/stale | Low | Only 19 animals profiled, data is recent (last 6 weeks) |

### Recommendation

**Enable all filters now.** The pre-checked "Unknown" default makes this safe — the vast majority of animals pass through. As more animals get profiled, the filters become increasingly useful without any further code changes.

**Optional enhancement:** Add an "Unknown" checkbox to the energy filter group to match the pattern of the other 3 compatibility filters. Without it, checking any energy filter excludes 95% of animals (those without notes).

---

REPORT COMPLETE — 132 lines.