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 specify_cli.mission_metadata import set_change_mode; \
              set_change_mode('<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/doctrine/templates/occurrence-map-template.yaml and the machine-enforced schema lives in src/doctrine/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.

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)

What to do when the gate blocks at implement time

If the user runs spec-kitty agent action implement WP## and sees a "Bulk Edit Gate: BLOCKED" panel, this means either:

• the occurrence map is missing (the author never set change_mode or skipped planning), or
• it fails structural validation (malformed YAML, missing required sections), or
• it fails admissibility (placeholder target, < 3 categories, missing any of the 8 standard categories).

Read the error panel. It names the specific problem. Fix the map, save, rerun the command. Do not use --force or any bypass.

What to do when diff compliance blocks at review time

If you're reviewing a WP and the command rejects with "Bulk Edit Review: Diff Compliance Violations", read the table. Each row shows one changed file, the category our path heuristic inferred, the action the map specified, and the verdict. BLOCK rows are the ones you need to address.

Three remediations, in order of preference:

1. Revert the offending change. If the file genuinely shouldn't have been touched (API schema, metric labels, historical migration), the implementation is wrong. Revert, rebuild, resubmit.

2. Narrow or add an exception in the occurrence map. When the category rule is too coarse (e.g., migrations/*.py: do_not_change blocks the new migration that implements the rename), refine the exception and re-commit the map.

3. Change the category rule. Only when the original category-level decision was genuinely wrong. Requires reviewer + user agreement; document the reason in exceptions[].reason.

Never:

• Edit the diff check to skip files (the check is the contract).
• Use git commit --no-verify-style bypasses (the gate lives at review claim, not at commit).
• Silently work around by splitting into smaller WPs so each one stays under the radar. The map applies across the whole mission.

Relationship to the inference warning

At implement time, if a mission is not marked bulk_edit but the spec content matches rename/migration keywords, the system prints a Bulk Edit Inference Warning. This is a nudge, not a block. If you see this warning, treat it as a signal that you (the agent) missed the detection during specify/plan and should have set change_mode earlier. Two options:

1. Upgrade the mission. Set change_mode: bulk_edit, draft the occurrence map, and ask the user to review before implementation resumes. This is usually the right call.

2. Explicitly dismiss only when you have read the spec and are certain this is NOT a bulk edit (e.g., the inference fired on a spec that happens to mention "rename" incidentally — "users can rename their own profile" describes a product feature, not a codebase rename). Pass --acknowledge-not-bulk-edit to proceed.

Dismissing carelessly defeats the guardrail. When in doubt, upgrade.

Quick reference

Files you'll touch

Related skills

• spec-kitty-runtime-next — the loop that runs implement/review; this skill produces the prerequisites it checks.
• spec-kitty-runtime-review — the review workflow that invokes the diff compliance check this skill's artifact governs.
• spec-kitty-glossary-context — closely related for terminology normalization; the glossary tells you what the canonical terms are, this skill governs how you migrate to them.