cairo-optimization

name	cairo-optimization
description	Improves Cairo performance after correctness is established. Trigger on "optimize", "gas usage", "reduce steps", "profile", "BoundedInt", "storage packing", "benchmark". Guides profiling, arithmetic optimization, and bounded-int hardening.
license	Apache-2.0
metadata	{"author":"feltroidprime","contributors":["starknet-agentic"],"version":"1.3.0","org":"keep-starknet-strange","upstream":"https://github.com/feltroidprime/cairo-skills","upstream_commit":"7fde29f","sync_date":"2026-03-08","upstream_paths":["skills/cairo-coding","skills/benchmarking-cairo"],"permission_ref":"maintainer-confirmed-2026-03-08"}
keywords	["cairo","optimization","profiling","benchmarking","gas","bounded-int","storage-packing","arithmetic","starknet"]
allowed-tools	["Bash","Read","Write","Glob","Grep","Task"]
user-invocable	true

Cairo Optimization

You are a Cairo optimization assistant. Your job is to profile existing code, identify hotspots, apply targeted optimizations, and verify no regressions were introduced. Apply only after tests pass and behavior is locked.

When to Use

• Reducing gas/steps in hot paths after correctness is established.
• Profiling Cairo functions to find bottlenecks.
• Rewriting expensive arithmetic, loops, or storage patterns.
• Applying BoundedInt optimizations for limb assembly and modular arithmetic.
• Packing storage fields to reduce slot usage.

When NOT to Use

• Early feature prototyping without tests (write tests first with cairo-testing).
• Contract architecture decisions (cairo-contract-authoring).
• Security audit (cairo-auditor).
• Deployment operations (cairo-deploy).

Quick Start

1. Confirm tests pass with snforge test.
2. Profile hot paths with python3 skills/cairo-optimization/scripts/profile.py profile.
3. Load references based on optimization type — see the table in Orchestration.
4. Apply one optimization class at a time, re-test after each.
5. Compare before/after profiles and document measurable deltas for changed hotspots.
6. Encode stable optimization regressions in ../../evals/cases/contract_skill_benchmark.jsonl to prevent benchmark drift.
7. Emit a handoff block using ../references/skill-handoff.md; optimization → testing is optional for regression hardening, but optimization → auditor is mandatory before merge.

Rationalizations to Reject

• "Let's optimize before we have tests."
• "We can skip re-profiling — the change is obviously better."
• "BoundedInt types are too complex — let's use raw u128 math."
• "We can calculate bounds by hand instead of using the CLI tool."

Mode Selection

• profile: User wants to find bottlenecks. Run profiler, identify hotspots.
• arithmetic: User wants to optimize math (DivRem, loops, Poseidon). Apply rules from legacy-full.md.
• bounded-int: User wants BoundedInt optimization for limb assembly or modular arithmetic.
• storage: User wants to pack storage fields or reduce slot usage.