run
alirezarezvani/claude-skills
Run a single experiment iteration: edit, evaluate, keep or discard.
What is run?
Execute one controlled experiment cycle within an autoresearch workflow. Review prior results, make a single targeted change to the target file, commit, evaluate, and report the outcome. Use when the user runs /ar:run or requests a manual iteration.
- Load experiment config, strategy, and historical results from the autoresearch branch
- Review prior runs to identify patterns in kept/discarded/crashed changes
- Decide a single, simple change based on strategy escalation (low-hanging fruit → systematic → structural → radical)
- Edit only the target file, commit the change, and run evaluation
- Report whether the change improved the metric, had no effect, or crashed
- Auto-update strategy documentation after every 10th iteration
How to install run
npx skills add https://github.com/alirezarezvani/claude-skills --skill run- Autoresearch experiment already initialized with config.cfg, program.md, and results.tsv
- Git repository with autoresearch/{domain}/{name} branch checked out
- Python environment with evaluation script (evaluate.py) configured
How to use run
- 1.Run /ar:run {domain}/{name} or /ar:run to list and select an experiment
- 2.Review the loaded config, strategy, and results.tsv to understand prior iterations
- 3.Decide one change based on the strategy escalation guidelines (runs 1-5: low-hanging fruit, 6-15: systematic, 16-30: structural, 30+: radical)
- 4.Edit only the target file specified in config.cfg with your single change
- 5.The skill commits your change and runs the evaluation script automatically
- 6.Review the reported result (KEEP/DISCARD/CRASH) and metric delta
- 7.After every 10th iteration, the strategy section of program.md is updated with learned patterns
Use cases
- Iteratively optimize API performance by testing one parameter change per run
- Explore algorithm improvements in a machine learning model with controlled experiments
- Systematically refactor code while measuring impact on test suite performance
- Debug why certain approaches fail by reviewing crash patterns in results history
- Escalate from simple tweaks to structural changes as experiment count grows
- Researchers running automated experiment workflows
- Engineers optimizing performance metrics incrementally
- Teams using autoresearch for systematic code improvement
- Developers who need reproducible, tracked iteration history
run FAQ
No. The skill enforces ONE change per iteration to isolate cause and effect. Multiple changes at once make it impossible to know which one caused the result.
The skill reverts the change automatically and reports the crash reason. Review evaluate.py to understand why, then try a different approach in the next iteration.
Early runs (1-5) target obvious improvements. Runs 6-15 vary one parameter systematically. Runs 16-30 swap algorithms. Runs 30+ try completely different approaches. The skill guides you based on results.tsv line count.
No. The evaluator is treated as ground truth and must never be modified. Only edit the target file.
After every 10th experiment, the skill automatically updates the Strategy section of program.md with patterns learned from the results.
Full instructions (SKILL.md)
Source of truth, from alirezarezvani/claude-skills.
name: "run" description: "Run a single experiment iteration. Edit the target file, evaluate, keep or discard. Use when the user runs /ar:run or asks for one manual autoresearch iteration." command: /ar:run
/ar:run — Single Experiment Iteration
Run exactly ONE experiment iteration: review history, decide a change, edit, commit, evaluate.
Usage
/ar:run engineering/api-speed # Run one iteration
/ar:run # List experiments, let user pick
What It Does
Step 1: Resolve experiment
If no experiment specified, run python {skill_path}/scripts/setup_experiment.py --list and ask the user to pick.
Step 2: Load context
# Read experiment config
cat .autoresearch/{domain}/{name}/config.cfg
# Read strategy and constraints
cat .autoresearch/{domain}/{name}/program.md
# Read experiment history
cat .autoresearch/{domain}/{name}/results.tsv
# Checkout the experiment branch
git checkout autoresearch/{domain}/{name}
Step 3: Decide what to try
Review results.tsv:
- What changes were kept? What pattern do they share?
- What was discarded? Avoid repeating those approaches.
- What crashed? Understand why.
- How many runs so far? (Escalate strategy accordingly)
Strategy escalation:
- Runs 1-5: Low-hanging fruit (obvious improvements)
- Runs 6-15: Systematic exploration (vary one parameter)
- Runs 16-30: Structural changes (algorithm swaps)
- Runs 30+: Radical experiments (completely different approaches)
Step 4: Make ONE change
Edit only the target file specified in config.cfg. Change one thing. Keep it simple.
Step 5: Commit and evaluate
git add {target}
git commit -m "experiment: {short description of what changed}"
python {skill_path}/scripts/run_experiment.py \
--experiment {domain}/{name} --single
Step 6: Report result
Read the script output. Tell the user:
- KEEP: "Improvement! {metric}: {value} ({delta} from previous best)"
- DISCARD: "No improvement. {metric}: {value} vs best {best}. Reverted."
- CRASH: "Evaluation failed: {reason}. Reverted."
Step 7: Self-improvement check
After every 10th experiment (check results.tsv line count), update the Strategy section of program.md with patterns learned.
Rules
- ONE change per iteration. Don't change 5 things at once.
- NEVER modify the evaluator (evaluate.py). It's ground truth.
- Simplicity wins. Equal performance with simpler code is an improvement.
- No new dependencies.
Related skills
More from alirezarezvani/claude-skills and the wider catalog.
sales-engineer
Analyzes RFP/RFI responses for coverage gaps, builds competitive feature comparison matrices, and plans proof-of-concept (POC) engagements for pre-sales engineering. Use when responding to RFPs, bids, or proposal requests; comparing product features against competitors; planning or scoring a customer POC or sales demo; preparing a technical proposal; or performing win/loss competitor analysis. Handles tasks described as 'RFP response', 'bid response', 'proposal response', 'competitor comparison', 'feature matrix', 'POC planning', 'sales demo prep', or 'pre-sales engineering'.
scrum-master
Advanced Scrum Master skill for data-driven agile team analysis and coaching. Use when the user asks about sprint planning, velocity tracking, retrospectives, standup facilitation, backlog grooming, story points, burndown charts, blocker resolution, or agile team health. Runs Python scripts to analyse sprint JSON exports from Jira or similar tools: velocity_analyzer.py for Monte Carlo sprint forecasting, sprint_health_scorer.py for multi-dimension health scoring, and retrospective_analyzer.py for action-item and theme tracking. Produces confidence-interval forecasts, health grade reports, and improvement-velocity trends for high-performing Scrum teams.
security-pen-testing
Use when the user asks to perform security audits, penetration testing, vulnerability scanning, OWASP Top 10 checks, or offensive security assessments. Covers static analysis, dependency scanning, secret detection, API security testing, and pen test report generation.
self-improving-agent
Curate Claude Code's auto-memory into durable project knowledge. Analyze MEMORY.md for patterns, promote proven learnings to CLAUDE.md and .claude/rules/, extract recurring solutions into reusable skills. Use when: (1) reviewing what Claude has learned about your project, (2) graduating a pattern from notes to enforced rules, (3) turning a debugging solution into a skill, (4) checking memory health and capacity.
senior-architect
This skill should be used when the user asks to "design system architecture", "evaluate microservices vs monolith", "create architecture diagrams", "analyze dependencies", "choose a database", "plan for scalability", "make technical decisions", or "review system design". Use for architecture decision records (ADRs), tech stack evaluation, system design reviews, dependency analysis, and generating architecture diagrams in Mermaid, PlantUML, or ASCII format.
senior-backend
Designs and implements backend systems including REST APIs, microservices, database architectures, authentication flows, and security hardening. Use when the user asks to "design REST APIs", "optimize database queries", "implement authentication", "build microservices", "review backend code", "set up GraphQL", "handle database migrations", or "load test APIs". Covers Node.js/Express/Fastify development, PostgreSQL optimization, API security, and backend architecture patterns.