Spec Kitty Bulk Edit Classification

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:

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())

The template is a complete, syntactically valid occurrence map with sane category defaults and placeholders only for target.term/target.replacement. Adjust per-category actions to fit the mission, then validate:

import yaml
from specify_cli.bulk_edit.occurrence_map import validate_against_schema

raw = yaml.safe_load((feature_dir / "occurrence_map.yaml").read_text())
result = validate_against_schema(raw)
assert result.valid, result.errors

Valid actions (exact strings — the gate rejects typos)

Default posture per category

This is a starting point to propose to the user. Tune per-project.

Multi-path structural moves (the moves: block)

The eight categories classify a single-term rename. They cannot express a structural relocation — moving one or more source paths to a single destination (src/legacy/auth/* → src/auth/). For those, add an optional top-level moves: block alongside the categories:

moves:
  - from:
      - src/legacy/auth/login.py
      - src/legacy/auth/session.py
    to: src/auth
    reason: "Consolidate auth modules under the canonical package"
  - from:
      - docs/old-guide.md
    to: docs/guides/getting-started.md
    reason: "Relocate and rename the onboarding guide"

Rules for moves::

• Each entry has a non-empty from list (one or more source paths) and a single to destination. reason is optional but recommended.
• Source and destination paths may be exact paths, globs (*/**), or a directory prefix (to: src/auth covers src/auth/login.py).
• A path that participates in a declared move is treated as a reviewer-approved relocation. At review time it is exempt from the do_not_change path heuristic — moving it is the whole point.
• The block is optional. A map with only the eight categories and no moves: validates and gates exactly as before — there is nothing new to fill in unless your mission actually relocates paths.

Use moves: when single-term renames cannot capture the change — for example when a paused restructure could only be described as path-to-path mappings. The categories still govern in-file string occurrences; moves: governs the relocation of whole paths.

Interviewing the user

The user knows the domain; you know the mechanics. For each category where the default is not obviously right, ask one concrete question. Keep the conversation short — for a typical rename, you need 2–4 questions.

Good question style:

"The rename will touch Customer inside API response bodies — e.g., {\"customer_id\": ...}. Changing those keys would break any client that has already integrated. I'd recommend keeping the JSON keys as customer_id (do_not_change) and only renaming the Python class. Sound right, or should we also do a versioned API migration?"

Bad question style:

"What action should I set for serialized_keys?" — (jargon the user doesn't have)