# Brownfield — Edit an Existing Case

Targeted changes to an existing `caseplan.case`. Skips the design handoff and the Phase 1–7 build pipeline. Terminates at `validate`, then hands off to Phase 5 (publish) / Phase 6 (debug) / Phase 7 (publish to Orchestrator).

> **Greenfield (new case from `sdd.md`) uses a different journey.** If `caseplan.case` does not yet exist, or the user wants to (re)build from a spec, see [planning.md](planning.md) → [implementation.md](implementation.md) → [phased-execution.md](phased-execution.md) instead.

## When this journey applies

`caseplan.case` already exists AND the user wants a targeted edit ("add a stage", "remove task X", "change this condition", "swap the trigger"). No `sdd.md`, no resolution phase, no planning phase, no prototyping hard stop. Routing lives in [SKILL.md](../SKILL.md#routing--greenfield-vs-brownfield).

## Kickoff — set dev expectations first

Before the first edit, present the flow once so the dev knows the steps and where they'll be asked to decide. Emit verbatim in tone (adjust wording to fit; keep the checkpoint markers). Present ONCE at entry; do not repeat. Allow-listed standalone text block (see [case-editing-operations.md § Hard token cap](case-editing-operations.md)).

> This is a targeted edit to an existing case (no full rebuild). Here's the flow:
> - I confirm where the case lives and **pull the latest** if it's in Studio Web (so a re-publish can't clobber server changes).
> - I make the edit, then **validate** and fix errors.
> - **Debug** (optional) — **you choose** whether to run the case for real (live emails / API calls).
> - **Publish** (optional) — **you choose** whether to upload to Studio Web.
> - **Publish to Orchestrator** (optional) — **you choose** whether to publish the case to Orchestrator.

## Pull latest first (before editing)

Most "edit an existing case" requests mean a case **deployed in Studio Web**, not just a local file. Editing the local `caseplan.case` and re-publishing (Phase 5 `uip solution upload`) **overwrites server state** — if the case changed in Studio Web after the local copy was made, the upload silently clobbers those changes, with no diff and no conflict check. Reconcile **before** the first edit.

1. **Determine where the case lives.** If not already known, AskUserQuestion: `Edit my Studio Web case (pull latest first)` (default) / `Edit a local-only project (no pull)`.
2. **Lives in Studio Web (has a SolutionId)** → pull current server state into the working dir before editing:
   - Standalone export: `uip solution download <SolutionId> -d <WorkingDir> --extract --output json` — exports the `.uis` archive and unpacks it; edit the extracted project.
   - Already-linked local solution project: `uip solution projects resync --project-name <ProjectName> --sync-option Sync --output json`.
   - SolutionId unknown → ask the user for it; never guess.
   - `--extract` / `resync` **overwrite the destination**. Run before any edit. If you have already edited the local copy this session, pulling discards those edits — confirm with the user first.
3. **Local-only project (no SolutionId)** → proceed as today, no pull.
4. The pull is a CLI boundary operation (like `uip solution upload`), not a Rule 14 artifact mutation — it runs once, before editing. After it, all edits resume via Read/Write/Edit only.
5. **Find the plan file by Studio Web's names, newest first: `caseplan.case`, `caseplan.json`, `case.stage.json`, `default.stage.json`.** Studio Web renames the plan to `caseplan.case` on its first save (with a `caseplan.case.bpmn` sidecar), and reads the newest name present. Edit and validate whichever name the pulled project has. Never create a `caseplan.case` beside an existing plan of another name, or the reverse — Studio Web reads only the newest name present, so the other file is silently ignored. Every `caseplan.case` path in this guide means the plan file found here.
6. **A designer-saved plan may declare a newer case schema than the installed CLI accepts.** If `validate` fails with `CASE_MGMT_VERSION_NEWER_THAN_SCHEMA`, stop and report it: the installed CLI cannot validate this plan yet. Never lower the `version` field to make validation pass — the plan was saved in the newer shape, and Studio Web would then read a document that misstates its own schema.

7. **A project Studio Web saved can carry a stale `bindings_v2.json`.** The Designer rewrites it on publish and debug, but a save rewrites it only when an entry point, a file name or the BPMN changed, so a task added in the Designer can be missing from it. Packing ships the file as it is. After a pull, or when the user says the project was just pulled, run `uip maestro case bindings sync "<ProjectName>/caseplan.case" --output json` before you validate, pack, upload or debug. Never edit `bindings_v2.json` by hand (Rule 14). `validate --strict` reports the lag as `STRICT_BINDINGS_SIDECAR_STALE`.

Record the outcome (pulled from SW at `<SolutionId>`, or local-only) for the freshness note in [Completion Output](#completion-output).

> **Do NOT regenerate from scratch.** SKILL.md Rule 7 ("always regenerate from scratch") is a greenfield/planning rule. Brownfield edits the file in place and preserves every node `id` / `elementId` — re-minting IDs breaks `=vars.*` references, conditions, and `entry-points.json`.

## Large or sweeping edits

Edit size never changes the journey — many edits still stay brownfield (in-place, IDs preserved). No complexity threshold escalates to greenfield. Batch multi-edit passes per [case-editing-operations.md § Per-section batch write contract](case-editing-operations.md#per-section-batch-write-contract--canonical): one `validate` at the end, not per edit.

When an edit touches many nodes or reads like "rebuild this case", confirm scope first via AskUserQuestion — `Edit in place` (default) vs `Rebuild from an updated spec` (greenfield via [planning.md](planning.md), re-mints IDs). Only an explicit rebuild choice or a new/updated `sdd.md` escalates to greenfield.

## Read this first

- **All mutations via Read/Write/Edit only** (Rule 14). CLI never mutates the case file in place: metadata fetches (`uip maestro case tasks describe`, `uip maestro case spec`, `is resources/triggers describe`), `uip maestro case validate`, the pre-edit pull (`uip solution download` / `solution projects resync` — see [§ Pull latest first](#pull-latest-first-before-editing)), and (on handoff) `uip solution resources refresh` / `uip solution upload` / `uip maestro case debug`. No `python`/`node`/`jq`/`sed`/`awk`/helper scripts touching the file.
- **`id-map.json` may be absent.** When editing a `caseplan.case` not built in this session, the `id-map.json` sidecar may not exist. Read node IDs directly from `caseplan.case`; do not assume the sidecar is present. If absent, do not synthesize one.
- **Connector edits need a metadata fetch first.** Adding/altering a connector-activity task or connector-bound rule requires `uip maestro case spec --type ...` (or `tasks describe`) before authoring the shape — never hand-author connector schemas. See [connector-integration.md](connector-integration.md).
- **Cross-cutting mechanics** (ID generation, Pre-flight Checklist, expression prefixes, per-section batch contract) live in [case-editing-operations.md](case-editing-operations.md). This doc routes; that doc supplies the recipe.

## Common edits

**Check [edit-recipes-guide.md](edit-recipes-guide.md) first.** It holds complete recipes for adding, changing, and removing tasks and stages; when one covers the edit, follow it instead of the rows below.

| Edit | Operation + recipe |
|---|---|
| Add / insert a stage | [case-editing-operations.md § Add a node](case-editing-operations.md#add-a-node-trigger--stage) + [plugins/stages/impl-json.md](plugins/stages/impl-json.md). Every regular stage needs ≥1 entry condition (Step 10). |
| Insert a stage between two existing stages | [case-editing-operations.md § Insert a stage between two existing stages](case-editing-operations.md#insert-a-stage-between-two-existing-stages) |
| Add a task to a stage | [case-editing-operations.md § Add a task to a stage](case-editing-operations.md#add-a-task-to-a-stage) + the task type's [plugins/tasks/<type>/impl-json.md](plugins/tasks/) |
| Bind / change a task input | [case-editing-operations.md § Bind an input](case-editing-operations.md#bind-an-input) + [bindings-and-expressions.md](bindings-and-expressions.md) |
| Move a task to a different stage or lane | [case-editing-operations.md § Move a task to a different stage or lane](case-editing-operations.md#move-a-task-to-a-different-stage-or-lane) |
| Remove / delete a task | [case-editing-operations.md § Delete a task](case-editing-operations.md#delete-a-task) |
| Add / change a condition (4 scopes) | the matching [plugins/conditions/<scope>/impl-json.md](plugins/conditions/) |
| Modify a condition rule in place (operator / expression / type) | [case-editing-operations.md § Modify a condition rule in place](case-editing-operations.md#modify-a-condition-rule-in-place) |
| Delete a condition rule (plain or connector, any scope) | [case-editing-operations.md § Delete a condition rule](case-editing-operations.md#delete-a-condition-rule) |
| Remove a case-exit completion / exit rule | [case-editing-operations.md § Delete a case-exit completion rule](case-editing-operations.md#delete-a-case-exit-completion-rule) |
| Replace a placeholder task with a real one | [case-editing-operations.md § Replace a placeholder task with an enriched task](case-editing-operations.md#replace-a-placeholder-task-with-an-enriched-task) + [placeholder-tasks.md](placeholder-tasks.md) |
| Re-sync a task whose source schema changed | [case-editing-operations.md § Re-sync a task after its source schema changed](case-editing-operations.md#re-sync-a-task-after-its-source-schema-changed) + the task type's [plugins/tasks/<type>/impl-json.md](plugins/tasks/) |
| Repoint a non-connector task at a different resource (swap which process/agent it runs) | [case-editing-operations.md § Repoint a non-connector task at a different resource](case-editing-operations.md#repoint-a-non-connector-task-at-a-different-resource) + the task type's [plugins/tasks/<type>/impl-json.md](plugins/tasks/) |
| Replace a trigger with a different type | [case-editing-operations.md § Replace a trigger with a different type](case-editing-operations.md#replace-a-trigger-with-a-different-type) |
| Re-target an event trigger (same type, different event) | [case-editing-operations.md § Re-target an event trigger](case-editing-operations.md#re-target-an-event-trigger-same-type-different-event) |
| Convert a Stage to/from an Exception Stage | [case-editing-operations.md § Convert a Stage to/from an Exception Stage](case-editing-operations.md#convert-a-stage-tofrom-an-exception-stage) |
| Delete a node (incl. a stage with successors — repoint their entry conditions) | [case-editing-operations.md § Delete a node](case-editing-operations.md#delete-a-node) |
| Delete a trigger (prune `entry-points.json` + In-arg variable cascade) | [case-editing-operations.md § Delete a node](case-editing-operations.md#delete-a-node) (Trigger branch, steps 5–6) |
| Delete a connector condition rule | [case-editing-operations.md § Delete a condition rule](case-editing-operations.md#delete-a-condition-rule) (connector cascade, steps 4–6) |
| Add SLA / escalation | [plugins/sla/impl-json.md](plugins/sla/impl-json.md) |
| Modify / remove an SLA or escalation | [case-editing-operations.md § Modify or remove an SLA or escalation](case-editing-operations.md#modify-or-remove-an-sla-or-escalation) |
| Add a global variable / argument | [plugins/variables/global-vars/impl-json.md](plugins/variables/global-vars/impl-json.md) |
| Rename / delete a global variable or argument | [case-editing-operations.md § Rename or delete a global variable or argument](case-editing-operations.md#rename-or-delete-a-global-variable-or-argument) + [plugins/variables/global-vars/impl-json.md](plugins/variables/global-vars/impl-json.md) |
| Change a variable's type or default | [case-editing-operations.md § Change a variable's type or default](case-editing-operations.md#change-a-variables-type-or-default) + [plugins/variables/global-vars/impl-json.md](plugins/variables/global-vars/impl-json.md) |
| Add or repair a response to an SLA at-risk / breach event | [§ SLA responses in a brownfield edit](#sla-responses-in-a-brownfield-edit) below, then [plugins/conditions/stage-entry-conditions/impl-json.md](plugins/conditions/stage-entry-conditions/impl-json.md) |

## SLA responses in a brownfield edit

An SLA clock and its **response** are separate edits. Pick the response, the status shape, and the interrupting value per [sla-response-shapes.md](sla-response-shapes.md) — that file is the contract; this section only says what it means for an edit.

- **Do not widen the edit.** A requirement that only asks to notify someone is `notify-only`: add an escalation to the target's `slaRules[].escalationRule` ([plugins/sla/impl-json.md](plugins/sla/impl-json.md)) and stop. No stage, no task, no condition.
- **`start-task` adds a task, not a lane** ([sla-response-shapes.md § 1](sla-response-shapes.md#1-pick-the-response)): the follow-up task goes in the breached stage with the `sla-status-change` rule as its **own task-entry** condition — never as a stage-entry row on the breached stage, which re-runs that stage's other tasks.
- **Four defects `validate` accepts** — re-read [§ 5](sla-response-shapes.md#5-four-defects-validate-cannot-see) before you finish: a task with no entry condition, a non-interrupting lane demoted to a regular stage, an `escalationId: "any"` "repaired" by repointing instead of deleting, and a `start-task` authored as stage re-entry.
- **`validate` passing is not evidence the response is right.** Every defect above validates clean.

## After edits

1. **Validate** — `uip maestro case validate <ProjectName>/caseplan.case --strict --output json` (fall back to the default profile only if the CLI rejects `--strict`, and say so). Authoritative; retry ≤3, fix on failure. On 3rd failure HARD STOP: AskUserQuestion `Retry with fix` / `Pause for manual edit` / `Abort` (same contract as Phase 4).
2. **Any edit that adds, removes, or repoints a resource binding — connector OR non-connector** — regenerate `bindings_v2.json` per [bindings-v2-sync.md](bindings-v2-sync.md), then `uip solution resources refresh --solution-folder <SolutionDir> --output json` (Rule 15) before any debug/publish. `bindings_v2.json` holds non-connector bindings too (process/agent/rpa/action/api-workflow/function/business-rule/case-management — [bindings-v2-sync.md § What `resource refresh` produces](bindings-v2-sync.md#what-resource-refresh-produces)); a stale file makes `uip solution upload` / `debug` throw "Resource is not configured". A pure schema-only re-sync (same resource, no binding change) needs no refresh. Repoint or removal → also prune the orphan ([bindings-v2-sync.md § Prune orphaned solution resources](bindings-v2-sync.md#prune-orphaned-solution-resources)). If step 1 reported `STRICT_BINDINGS_UNREFERENCED`, the edit left root bindings nothing uses: repair per [validator-codes.md § Binding cleanup](validator-codes.md#binding-cleanup--unreferenced-root-bindings) before finishing — a `Valid` carrying that warning is not done.

## Completion Output

Report: file path edited, what changed (nodes/tasks/conditions added/removed/modified), validation status, any placeholder tasks still unresolved, any connector connections the user must create, and a **freshness note** — whether the local copy was pulled from Studio Web first (so re-publish reflects current server state) or is a local-only project not synced from SW (re-publish overwrites whatever is on the server). Then include `Suggested next steps` in one short line before AskUserQuestion "What's next": publish when ready to update Studio Web, run debug if the edit changes runtime behavior, or stop and inspect the local diff.

| Option | What it does |
|---|---|
| **Publish to Studio Web** | Phase 5 — `uip solution resources refresh` then `uip solution upload <SolutionDir> --output json --output-filter "{Status: Status, Action: Action, SolutionId: SolutionId, DesignerUrl: DesignerUrl}"` (filter mandatory — see [case-commands.md § uip solution upload](case-commands.md#uip-solution-upload)), print DesignerUrl and the `Action` (`Imported`/`Overwritten`). |
| **Run debug session** | Phase 6 — executes the case for real (consent-gated, Rule 13). |
| **Publish to Orchestrator** | Phase 7 — `uip maestro case pack` (mandatory BPMN recompile), then `uip solution pack`, then `uip solution publish` to the tenant solution feed (consent-gated, Rule 13). |
| **Done** (default) | Stop here. |
| **Something else** | Free-form. |

Do not run debug, publish, or publish to Orchestrator without explicit selection. On selection, follow the existing [phased-execution.md](phased-execution.md) Phase 5 / Phase 6 / Phase 7 contracts.

<!-- END: brownfield.md -->
