clarity overhaul using syntax check and lint