# Mutation

Mutation commands change code through TS/IDE refactors.
Successful mutations update affected references and imports.

After a successful mutation, do not manually patch the same imports unless aib reports a follow-up or checks show a real issue.

AIB mutations are designed to reduce manual checking.
Your job is to express the intent in DSL.
AIB's job is to convert that intent into code changes.

Do not read all changed files just because a mutation touched them.
That defeats the purpose of using AIB for mechanical refactors.

If the command succeeds, the requested mechanical change was applied.
After failure or partial success, use the output to decide the next request.

When running mutation commands, set the harness timeout to 3 minutes.
If the harness stops waiting before final output appears, recover with:

aib execution status last

Modes:
preview  inspect planned edits, then apply by id
apply    write a previewed change
execute  write immediately

Use execute for routine rename/move/modulePlan requests.

Use preview/apply when you are learning a mutation command, or when one request contains a large multi-step change that you want to inspect before writing files.
Typical examples: a huge modulePlan or refactor batch.

preview/apply uses more tool calls and more output tokens.
preview validates input and planned edits, but writing files can still hit a TS/IDE refactor error.
execute writes immediately and reports what changed.

If a mutation cannot be completed, aib reports the failed part.

Prefer batch DSL for related mutations.
One request can describe several related changes.

When a batch mutation partly fails, split the next request by failure type.

If the failure is wrong input, fix the selector/entity/file and run the corrected remaining intent.
If TS/IDE cannot apply one part of the batch, do not treat the whole intent as failed.
Run the next request without the failed part and let aib report any later failures.
Then decide whether failed parts need smaller requests or manual fallback.
