> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Change a published Shape

> Edit an existing Shape, review the effect on current records, publish the new version, and verify it in Runtime.

Use this when the same Shape needs to evolve for its current users. If you want
a separate variant that can change independently, [fork the Shape](/shapes/fork-a-variant)
instead.

## Before you start

* Identify the project, Shape, and published version you intend to change.
* Write the requested change in domain language.
* Find one current record that should still work afterward.

## Ask your agent

> Open the Customer Discovery Shape for editing. Rename the existing `impact`
> field on findings to `decision_impact` without replacing the field with a new
> one. Show the current value and field definition, make the rename, compile the
> draft, show the exact diff, and check the effect on existing records. Do not
> publish until I approve.

## Steps

<Steps>
  <Step title="Open the published version">
    The agent checks the version history and shows the current field before opening an edit draft.
  </Step>

  <Step title="Make the smallest change">
    For a rename, use the rename operation. Removing the field and adding another one can break its connection to existing records and make migration harder to review.
  </Step>

  <Step title="Compile and read the diff">
    Confirm that the diff contains the requested change and no unrelated removals or restrictions.
  </Step>

  <Step title="Check the version and migration">
    Make sure the draft still targets the published version you inspected. Then review how records using the old field will be handled.
  </Step>

  <Step title="Preview and dry-run publication">
    Check the new Runtime field name, then run publication without applying it.
  </Step>

  <Step title="Approve and publish">
    Publish only after the diff, migration plan, target project, and dry-run result match the requested change.
  </Step>

  <Step title="Read an existing record in Runtime">
    Inspect the Shape and the record you selected before editing. Confirm that the renamed field still carries the intended value.
  </Step>
</Steps>

## Verify

Runtime should show `decision_impact` on the updated Shape, and the existing
record should retain the value that previously appeared under `impact`.

## Troubleshooting

* **The published version changed while you worked:** reopen the current version, compare it with the draft, and reconcile before publishing.
* **The field's meaning changed as well as its name:** treat that as more than a rename. Add or migrate the field deliberately and review the affected records.
* **The migration lists unexpected records:** stop and inspect why they use the changed field before approving.
* **Both versions need to remain available:** [fork the Shape](/shapes/fork-a-variant) instead of editing the original.

<Accordion title="Tool trace">
  ```text theme={null}
  shape_workbench_version_graph
  → shape_workbench_open({ mode: "edit" })
  → shape_workbench_rename_property / shape_workbench_edit_property
  → shape_workbench_compile
  → shape_workbench_assert_version_alignment
  → shape_workbench_diff
  → shape_workbench_plan_migration
  → shape_workbench_preview_operating_surface
  → shape_workbench_materialize({ dry_run: true, review_note: "..." })
  → approval and publication
  → Runtime: penumbra_introspect
  → Runtime: penumbra_read
  ```
</Accordion>