Change a published Shape

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

Open the published version

The agent checks the version history and shows the current field before opening an edit draft.

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.

Compile and read the diff

Confirm that the diff contains the requested change and no unrelated removals or restrictions.

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.

Preview and dry-run publication

Check the new Runtime field name, then run publication without applying it.

Approve and publish

Publish only after the diff, migration plan, target project, and dry-run result match the requested change.

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.

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 instead of editing the original.

Tool trace

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

Begin

Design and publish

Evolve

Change a published Shape

Before you start

Ask your agent

Steps

Verify

Troubleshooting

​Before you start

​Ask your agent

​Steps

​Verify

​Troubleshooting

Before you start

Ask your agent

Steps

Verify

Troubleshooting