wicked-patch

Generate and propagate code changes across your entire codebase using the symbol graph.

All sub-actions run the patch CLI. The full invocation is:

wicked-garden run scripts/engineering/patch/patch.py <sub-action> [args]

Examples below abbreviate this to patch.py <sub-action> … — always run the full form.

The propagation diagram, quick-start recipes, per-action examples, the sample
PROPAGATION PLAN / GENERATED PATCHES output, the patches-file JSON schema,
and the language/type/SQL-dialect reference tables live in
refs/output-samples.md.

Runtime

Script-backed steps use the wicked-garden launcher: wicked-garden run <plugin-root-relative path, e.g. scripts/…> [args]. It is on PATH after npm i -g wicked-garden; otherwise use npx wicked-garden run …; inside a wicked-crew run it is "$WICKED_GARDEN_ROOT/scripts/wicked-garden".
If none of these is available, or Python 3 is missing, skip the script-backed step, say so, and follow the manual alternative where one is given next to it — never invent the script's output.
Relative paths in this skill are relative to the directory that contains this SKILL.md.

Sub-actions

Sub-action	Purpose
patch-plan	Show what would be affected — propagation preview, no patches
add-field	Add field with propagation
rename	Rename across all usages
remove	Remove field everywhere (DELETES code — see warning)
apply	Apply saved patches from a JSON file
new-generator	Author a new language generator (refs/new-generator.md)

patch-plan — propagation preview

Show what would be affected by a change without generating patches. Distinct
from the engineering domain skill's plan action (a human implementation plan
with risks and tests) — patch-plan is the impact preview for mechanical patches.
The CLI subcommand is plan.

Arguments: symbol_id (required — symbol to analyze); --change
(add_field | rename_field | remove_field | modify_field); --depth
(max traversal depth, default 5); --json (output as JSON).

wicked-garden run scripts/engineering/patch/patch.py plan "<symbol_id>" --change "<change_type>" [--json]

See refs/output-samples.md for examples and the sample PROPAGATION PLAN output.

add-field — add a field and propagate

Add a field to an entity/class and propagate to all affected files.

Arguments: symbol_id (required — e.g. path/Entity.java::EntityName);
--name (required — field name); --type (required — String, Integer, Boolean,
Date, etc.); --column (database column name, defaults to SNAKE_CASE of name);
--label (UI label for form fields); --required (mark field non-nullable);
--output/-o (save patches to JSON file); --apply (apply patches
immediately); --verbose/-v (show full diffs).

wicked-garden run scripts/engineering/patch/patch.py add-field "<symbol_id>" \
  --name "<name>" \
  --type "<type>" \
  [--column "<column>"] \
  [--required] \
  [--verbose]

See refs/output-samples.md for examples, a JPA entity walkthrough (generated Java/SQL), and the GENERATED PATCHES output.

rename — rename a field/symbol across all usages

Arguments: symbol_id (required); --old (required — current field name);
--new (required — new field name); --output/-o (save patches to file);
--apply (apply patches immediately); --verbose/-v (show full diffs).

wicked-garden run scripts/engineering/patch/patch.py rename "<symbol_id>" --old "<old_name>" --new "<new_name>" [--verbose]

What gets updated:

• Field declarations
• Getter/setter method names
• Property references (this.oldName → this.newName)
• JSP EL expressions (${entity.oldName} → ${entity.newName})
• Form bindings (path="oldName" → path="newName")
• TypeScript interfaces and type aliases
• SQL column names (generates ALTER TABLE RENAME COLUMN)
• Service layer references, and test files (with warning)

remove — remove a field and all its usages

Arguments: symbol_id (required); --field (required — field name to
remove); --output/-o (save patches to file); --apply (apply patches
immediately); --verbose/-v (show full diffs).

wicked-garden run scripts/engineering/patch/patch.py remove "<symbol_id>" --field "<field_name>" [--verbose]

Warning

This operation DELETES code. Always review patches before applying:

# Generate and save patches
patch.py remove SYMBOL --field foo -o patches.json

# Review
cat patches.json

# Apply when confident
patch.py apply patches.json

apply — apply patches from a saved JSON file

Arguments: patches_file (required — path to patches JSON file);
--dry-run (show what would be done without applying).

wicked-garden run scripts/engineering/patch/patch.py apply "<patches_file>" [--dry-run]

See refs/output-samples.md for the save→review→dry-run→apply workflow and the patches-file JSON schema.

new-generator — create a new language generator

Create a new language generator for wicked-patch with scaffolding, golden test
fixtures, and conformance validation. Arguments: language (required, e.g.
"scala", "swift", "elixir"); framework (optional ORM/framework, e.g. "Slick",
"CoreData", "Ecto"); extensions (optional file extensions, defaults to
lowercase language). Follow the full 7-step authoring workflow (generator
template with TYPE_MAP, __init__.py registration, golden fixture JSON,
test_conformance.py additions, run tests, report) in
refs/new-generator.md.

Language & type reference

Supported languages (.java, .py, .ts/.js, .jsp, .sql), the generic→
per-language type mappings, and SQL dialect support (PostgreSQL / Oracle / MySQL /
SQL Server, auto-detected or via --dialect) are tabulated in
refs/output-samples.md.

Building the symbol database (wicked-estate)

wicked-patch reads a --db translated from the wicked-estate code graph
(ADR 0005). Build the store, then translate it:

wicked-estate index . --db .codegraph/estate.db   # or reuse a crew-materialized store
wicked-garden run scripts/engineering/patch/estate_db.py \
  [--estate-db .codegraph/estate.db] [--out .wicked/patch-symbols.db]

In a governed run (a unit of a wicked-crew run; when unsure, assume so) the store is
handed to you — pass it as --estate-db "$WICKED_ESTATE_DB"; never run wicked-estate index
inside a run (the write CLI is denied there; the wicked-garden-search ladder applies).

estate_db.py auto-discovers the store ($WICKED_ESTATE_DB, then
.codegraph/estate.db, then .wicked-estate/graph.db); pass the resulting
--db .wicked/patch-symbols.db to the patch sub-actions. Symbol ids keep the
patch-native file::Name scheme (e.g. src/app.py::Order).

Safety Features

• Dry-run by default: Shows patches without applying
• Confirmation prompt: Asks before applying
• Patch files: Save for review before applying
• Warnings: Highlights test files and unsupported types
• Reversible: Use git to undo

CLI Reference

wicked-garden run scripts/engineering/patch/patch.py --help
wicked-garden run scripts/engineering/patch/patch.py generators  # List supported languages