Revit cleanup scripts should write reports before they change the model.
Not after.
Before.
The report is not paperwork. It is the moment where the team can still catch the wrong scope, the wrong category, the wrong naming rule, the wrong parameter, or the wrong assumption before automation turns it into model history.
If a script can rename families, delete views, rewrite parameters, rebind shared parameters, update sheets, purge content, fix type marks, normalize room data, or touch hundreds of elements at once, the first output should be evidence.
The model can wait.
The problem
Cleanup work looks safer than design work because it sounds like removing mess.
That is the trap.
A cleanup script can still damage production. It can delete a view that looked unused but was needed for a consultant reference. It can rewrite a parameter that a tag depends on. It can rename family types in a way that breaks schedules. It can change sheet metadata right before an issue. It can bind shared parameters too broadly and make the model noisier instead of cleaner.
The script might be technically correct and still operationally wrong.
The team needs a way to review what the script believes before it acts.
That way is a report.
What the report should answer
A useful pre-change report should answer five questions.
What did the script inspect?
What does it want to change?
Why does it want to change those things?
What will it refuse to touch?
What evidence lets a human approve or reject the run?
If the report cannot answer those questions, the script is still guessing in public.
Start with inventory
The first report does not need to be beautiful.
It needs to be specific.
For each affected element, include:
- element id
- category
- family and type when relevant
- current value
- proposed value
- rule that matched it
- action type
- risk or warning
- whether the change is automatic or review-only
For views and sheets, include placement status, template, sheet number, sheet name, and whether the item appears in a deliverable set.
For shared parameters, include name, GUID, binding, category scope, and whether a schedule, tag, export, or script depends on it. That is the same interface discipline behind Shared parameters are an interface.
For family cleanup, include the naming rule and the exact before/after names. Boring naming rules only help if the script can show how it applied them.
Reports create a review gate
The report is where a cleanup script becomes a team workflow instead of a private trick.
Someone can scan the proposed changes.
Someone can spot the category that should not be touched.
Someone can reject a broad wildcard before it catches real deliverables.
Someone can approve only the safe subset.
Someone can save the report with project notes so the next person understands what happened.
That is why BIM automation must survive handoff is not just a documentation idea. Handoff starts before the change, when the script explains itself clearly enough for another person to judge.
Write-only cleanup is risky
A script that only has a run button is asking for trust it has not earned.
Preview should be the default mode.
Commit should be explicit.
Rollback should be planned.
The safest order is:
- scan the model
- write the report
- review the report
- snapshot the affected data
- run the approved change
- write the result report
- store both reports with the project record
That sequence gives the team an evidence trail.
If the script changes 312 elements, the team should not learn that from vibes. It should have a count, a list, and a reason.
What to include in the result report
The post-run report should not merely say success.
It should include:
- elements scanned
- elements changed
- elements skipped
- elements failed
- warnings
- old values
- new values
- model name
- Revit version
- script version or commit
- operator
- timestamp
- backup or rollback location
Skipped items matter.
Failures matter.
Warnings matter.
A cleanup script that hides partial failure is worse than a manual process because it can make the model look clean while burying the evidence.
The rollback connection
Reports and rollback belong together.
The rollback plan in Dynamo cleanup scripts need a rollback plan depends on knowing what changed. If the script does not record old values, new values, and affected element ids, rollback becomes archaeology.
Sometimes rollback is a model backup.
Sometimes it is an exported CSV of old parameter values.
Sometimes it is a transaction group.
Sometimes it is a script that reverses the approved change list.
Whatever the method, the report is the map.
Common traps
The first trap is reporting only counts.
“Changed 142 elements” is better than silence, but it is not reviewable. The team needs to know which elements and why.
The second trap is reporting only after commit.
That helps record history, but it does not prevent the wrong change. The pre-change report is the control point.
The third trap is putting reports in a random local folder.
If the report matters, store it where the project team can find it. A local desktop path is not handoff.
The fourth trap is letting the report be too technical for the owner of the model.
Element ids are useful. They are not enough. Include human-readable names, categories, sheet numbers, view names, and parameter names.
The fifth trap is treating the report as optional because the script is “just cleanup.”
Cleanup is exactly where broad rules sneak in.
A practical finish line
Before a Revit cleanup script can touch a live model, it should be able to produce a pre-change report that another competent team member can review.
The reviewer should be able to answer:
- Does the target list make sense?
- Are the excluded items sensible?
- Are any categories too broad?
- Are any deliverables at risk?
- Is the rollback evidence present?
- Is the script version clear?
- Do we know where the report will be stored?
If those questions are answerable, the script is becoming a tool.
If they are not, it is still a gamble with a nicer interface.
Verdict
Revit cleanup scripts should write reports first because cleanup is still change.
A report makes the blast radius visible.
It gives the team a review gate.
It gives rollback a map.
It gives the next person a record.
Write the report. Review the report. Then change the model.
That order saves projects from confident automation doing the wrong thing quickly.
— Ahmed