/spec-kitty-bulk-edit-classification

name: spec-kitty-bulk-edit-classification
description: >-
  Recognize when a mission is a bulk edit and drive the occurrence-classification
  guardrail on the user's behalf. Triggers: user says any variant of "rename X
  to Y", "change the terminology", "migrate all occurrences", "replace across
  the codebase", "the X feature is now the Y feature", "sed everywhere", or any
  request that touches the same identifier/path/key in many files. Also
  triggers on gate errors mentioning "change_mode", "occurrence_map.yaml",
  "Bulk Edit Gate: BLOCKED", or "Bulk Edit Review: Diff Compliance".
  Does NOT handle: line-level semantic refactors inside one file, adding a new
  feature that creates new identifiers without changing existing ones, or
  reviewing finished missions for fidelity.

spec-kitty-bulk-edit-classification

Drive the occurrence-classification guardrail (shipped in #393, DIRECTIVE_035) so users never have to know it exists. A bulk edit is any change that touches the **same string** in many places — a rename, a terminology migration, a package-path move, a feature-label swap. Those changes look mechanical but aren't: the same token carries different meaning depending on where it appears (code symbol, import path, filesystem literal, serialized key, CLI command, user-facing string, test fixture, log/telemetry label). Treating them uniformly is how silent breakage happens.

**The user will not say "bulk edit".** They will say "rename Coffee to Tea" or "the Blue feature is now the Red feature." Your job is to recognize that shape, turn on `change_mode: bulk_edit`, and drive the classification workflow before any code changes.

---

When to activate

Apply this skill during **specify** or **plan** when the user's description matches any of these patterns:

| Pattern | Example phrasing | |---|---| | Explicit rename | "Rename `Customer` to `Account` across the codebase" | | Terminology migration | "We're calling it 'channels' now, not 'streams'" | | Feature relabel | "The Blue feature is now the Red feature" | | Path/module move | "Move `src/legacy/auth` to `src/auth`" | | API surface rename | "Rename the `/users` endpoint to `/accounts`" | | Config key rename | "Change `max_connections` to `connection_limit` everywhere" | | Brand / product rename | "Replace ACME with GlobalCorp in all docs and UI" |

Also apply when the implement or review command prints a message starting with **"Bulk Edit Gate: BLOCKED"** or **"Bulk Edit Review: Diff Compliance"** — these are the runtime gates' failure output; this skill tells you how to respond.

**Do NOT apply when** the user is:

• Adding a genuinely new feature (new identifiers, new files) — no existing

identifiers change

• Refactoring the internals of one file or one function — no cross-cutting

string change

• Fixing a bug where the surface names stay the same

---

The core decision tree

At the start of `specify` or `plan`, after you understand the user's intent, ask yourself this one question:

> Does fulfilling this request require changing the **same existing string** > (identifier, path, key, label) in more than one file?

If **yes**: this is a bulk edit. Set `change_mode: bulk_edit` and run the classification workflow below.

If **no**: proceed normally. The guardrail stays dormant.

If **uncertain**: treat as bulk edit. The cost of a false positive is drafting an occurrence map the user can approve in one pass. The cost of a false negative is the silent-breakage class of bugs #393 was created to prevent.

---

What to do during specify

1. **Detect intent.** Read the user's feature description. If it matches the patterns above, you have a bulk edit.

2. **Set `change_mode` in `meta.json`.** Use the CLI helper — do not hand-edit JSON:

   from specify_cli.mission_metadata import set_change_mode
   set_change_mode(feature_dir, "bulk_edit")

Or via shell after `mission create`:

   python -c "from pathlib import Path; from specify_cli.mission_metadata import set_change_mode; \
              set_change_mode(Path('<feature_dir>'), 'bulk_edit')"

3. **Name the target in the spec.** In `spec.md`, state explicitly what's being renamed and to what:

> "This mission renames `Customer` (old term) to `Account` (new term) > across the codebase, with per-category rules captured in > `occurrence_map.yaml`."

Do NOT rely on the reviewer inferring the rename from prose. Make it an explicit claim that the occurrence map must satisfy.

4. **Tell the user, briefly**, that you're turning on the classification workflow. Use plain language — they don't need to know the field name:

> "This is a cross-cutting rename, so I'm going to produce an > `occurrence_map.yaml` during planning that decides which kinds of > occurrences get renamed vs. left alone (API response keys, CLI commands, > and metric labels are typically left alone to avoid breaking consumers). > You'll review and approve that map before any code changes."

---

What to do during plan

Produce `kitty-specs/<mission>/occurrence_map.yaml` with **all 8 standard categories present**. Leaving a category out is an error the gate rejects — every standard risk surface must have an explicit action assignment.

The template to fill

The starter template lives in `src/charter/offering/templates/occurrence-map-template.yaml` and the machine-enforced schema lives in `src/charter/offering/schemas/occurrence-map.schema.yaml`. Do not copy the shape from prose — load the actual file so you never drift from the contract that the runtime gate enforces:

from specify_cli.bulk_edit.occurrence_map import (
    load_template_text,     # starter YAML text to seed occurrence_map.yaml
    load_schema,             # JSON Schema dict (Draft 2020-12)
    validate_against_schema, # raw dict -> ValidationResult
)

# Seed the file:
(feature_dir / "occurrence_map.yaml").write_text(load_template_text())

Th