story_revision_run
CHANGE or POLISH structured story material that already exists in the project. The verb is CHANGE: alter, refine, or explore alternative directions for cards, scenes, or beats that have already been built. Wraps Change Story (proposes structural changes from a free-form direction), Polish Screenplay (suggests scene-level dialogue and style refinements), Creative Canvas (generates alternative directions for selected cards without committing them), and Scene List Revision (proposes concrete scene-list merges, deletes, reorders, beat-link updates, and scaffold reconciliation before prose rewrite).
When to use
The structured material already exists and you want to alter, refine, or explore alternatives — the verb is CHANGE.
Use `change_wizard` when proposing structural changes across cards based on a free-form direction.
Use `scene_list_revision` when the requested change primarily affects scenes, scene order, scene merges, scene deletions, or scene-to-beat links.
Use `polish_wizard` when refining existing scene-level dialogue and style without restructuring the story.
Use `creative_canvas` when generating alternative directions or what-ifs for selected cards rather than committing changes immediately.
When not to use
Do not use for direct point edits when screenplay tools fit better.
Do not use to **build** new structured material that does not exist yet — use `story_development_run` (beat_wizard, scene_wizard, story_bootstrap) instead.
Do not use `change_wizard` to fill empty treatment sections; use `story_development_run` with `workflow=treatment_wizard`.
Do not use to **get editorial feedback** without proposing changes — use `story_review_run` (room_review, analysis_wizard, continuity_audit) instead.
Do not use to **rewrite screenplay prose** — use `screenplay_edit_propose` / `screenplay_edit_apply` for surgical edits, or `screenplay_generation_run` for whole-screenplay regeneration.
Do not use `change_wizard` for scene-list condensation or scene merges; use `scene_list_revision` so the scene cards and screenplay scaffold change before prose rewrite.
Examples
“Run a change wizard over this project.”
“Explore new directions in Creative Canvas for selected cards.”
“Boundary - "Polish the existing scene list for better flow." Use `polish_wizard` here because the scenes already exist; this is CHANGE, not BUILD.”
“Boundary - "Restructure act 2 around a betrayal beat." Use `change_wizard` here because the caller wants to commit changes, not just receive feedback.”
“Boundary - "Merge these three procedural scenes into one sharper set piece." Use `scene_list_revision` because the scene list itself must change before screenplay prose.”
Anti-examples
- Show me template manifests.
- Generating a brand-new scene outline from an idea — that is `story_development_run` with `scene_wizard` or `story_bootstrap`.
- Fill treatment cards 50.10.10-50.10.40 from scratch — that is `story_development_run` with `treatment_wizard`.
- Asking for editorial scores or notes without applying any changes — that is `story_review_run` with `analysis_wizard` or `room_review`.
- Writing screenplay prose from the existing outline — that is `screenplay_generation_run` with `screenplay_writer`.
Workflows
Switch behavior by setting the workflow input field.
change_wizard
scene_list_revision
polish_wizard
creative_canvas
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"workflow",
"phase",
"project_id"
],
"properties": {
"workflow": {
"type": "string",
"enum": [
"change_wizard",
"scene_list_revision",
"polish_wizard",
"creative_canvas"
]
},
"phase": {
"type": "string",
"enum": [
"readiness",
"start",
"finalize",
"apply"
]
},
"project_id": {
"type": "integer"
},
"job_id": {
"type": "string"
},
"reservation_id": {
"type": "string"
},
"proposal_id": {
"type": "string",
"description": "Saved diff proposal id returned by scene_list_revision finalize; required for scene_list_revision apply."
},
"operation_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional selected scene operation ids to apply from a scene_list_revision proposal. Merge/delete dependencies are enforced server-side."
},
"payload": {
"type": "object",
"properties": {
"change_request": {
"type": "string",
"description": "Free-form revision direction. Required for change_wizard and scene_list_revision start."
},
"scene_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional scene ids/codes to focus scene_list_revision context."
},
"sequence_numbers": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Optional sequence numbers to focus scene_list_revision context."
},
"constraints": {
"type": "object",
"description": "Scene List Revision constraints. preserve_beat_codes and preserve_scene_ids are enforced at finalize/apply; max_scene_deletions limits delete/merge absorption count.",
"properties": {
"preserve_beat_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Beat codes that must remain linked to a surviving scene after apply."
},
"preserve_scene_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Scene ids that must not be deleted or absorbed."
},
"max_scene_deletions": {
"type": "integer",
"description": "Maximum number of scenes that may be deleted or absorbed by merge operations."
}
},
"additionalProperties": true
},
"operation_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"beat_changes": {
"type": "array",
"items": {
"type": "object"
}
},
"prompt": {
"type": "string"
},
"preset_id": {
"type": "string"
},
"model_hint": {
"type": "string"
},
"snapshot_rev": {
"type": "integer"
},
"selected_card_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"canon_excluded_card_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"visible_group_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"refinement_text": {
"type": "string"
},
"discussion_turns": {
"type": "array",
"items": {
"type": "object"
}
},
"current_directions": {
"type": "array",
"items": {
"type": "object"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"workflow",
"phase"
],
"properties": {
"workflow": {
"type": "string"
},
"phase": {
"type": "string"
},
"async": {
"type": "boolean"
},
"job_id": {
"type": "string"
},
"reservation_id": {
"type": "string"
},
"readiness": {
"type": "object"
},
"result": {
"type": "object"
},
"resource_links": {
"type": "array",
"items": {
"type": "object"
}
},
"pipeline_state": {
"$ref": "./_common/pipeline_state.schema.json"
},
"next_actions": {
"type": "array",
"items": {
"$ref": "./_common/next_action.schema.json"
}
}
},
"additionalProperties": true
}