winning-avg-corewars

Original source / Raw SKILL.md

---
name: winning-avg-corewars
description: Guidance for developing CoreWars warriors that achieve target win rates against specific opponents. This skill should be used when tasks involve writing, optimizing, or debugging Redcode assembly warriors for the CoreWars programming game, particularly when win rate thresholds must be met against multiple opponents.
---

# CoreWars Warrior Development

## Overview

This skill provides a systematic methodology for developing CoreWars warriors that achieve specified win rate thresholds against multiple opponents. It emphasizes deep opponent analysis, systematic parameter tuning, automated testing, and targeted strategy development rather than ad-hoc trial-and-error approaches.

## Prerequisites

Before beginning warrior development:

1. Verify pmars (Portable MARS) is available for testing battles
2. Identify all opponent warriors and their required win rate thresholds
3. Read and understand the opponent warrior code before writing any counter-strategies
4. Determine core size and other battle parameters from the task requirements

## Development Workflow

### Phase 1: Opponent Analysis

Before writing any warrior code, thoroughly analyze each opponent:

1. **Read opponent source code** - Understand the warrior's strategy, not just observe its behavior
2. **Categorize opponent type** - Identify if it's a bomber, scanner, replicator, imp, paper, stone, or hybrid
3. **Extract exploitable patterns**:
   - What step/interval does it use for bombing or scanning?
   - What positions in the core does it avoid or target?
   - Does it have predictable timing or movement patterns?
   - What are its weaknesses (e.g., vulnerable to imps, slow startup)?

4. **Document findings** - Create a brief profile for each opponent:
   ```
   Opponent: stone.red
   Type: Bomber
   Step: 4 (bombs every 4 positions)
   Weakness: Predictable bombing pattern, vulnerable to positions not divisible by 4
   Counter-strategy ideas: Use step sizes that avoid multiples of 4
   ```

### Phase 2: Strategy Selection

Based on opponent analysis, determine appropriate warrior archetypes:

**Common CoreWars Warrior Types:**
- **Scanner**: Searches for enemies before attacking
- **Bomber**: Blindly drops DAT bombs at regular intervals
- **Replicator (Paper)**: Creates copies of itself throughout the core
- **Imp**: Simple MOV 0,1 that creates self-propagating spirals
- **Vampire**: Uses JMP traps to capture enemy processes
- **Stone**: Bomber with defensive spl/jmp stuns
- **Silk**: Optimized replicator with specific step patterns

**Strategy Decision Tree:**
1. Against slow bombers → Fast replicators or scanners
2. Against replicators → Scanners with quick-scan or vampires
3. Against imps → Imp gates (spl 0, dat 0 pairs) or core clears
4. Against scanners → Decoys combined with attack components
5. Against core clears → Fast-spreading replicators

### Phase 3: Initial Implementation

Start with simple, focused warriors rather than complex multi-component designs:

1. **Begin minimal** - Test the simplest version of chosen strategy first
2. **One component at a time** - Add complexity only after understanding base performance
3. **Use proven patterns** - Reference established CoreWars strategies from documentation
4. **Avoid premature optimization** - Get basic functionality working before tuning

### Phase 4: Systematic Testing

Use the automated test script (`scripts/test_warrior.sh`) for consistent evaluation:

```bash
./scripts/test_warrior.sh warrior.red
```

**Testing principles:**
- Run sufficient rounds (100+) for statistical significance
- Track results in a structured format across iterations
- Test against ALL opponents after every change, not just the one being targeted
- Record parameter values alongside results for later analysis

### Phase 5: Parameter Optimization

When tuning parameters (step sizes, gate positions, spl counts):

1. **Systematic search** - Use grid search or binary search over parameter ranges
2. **Understand relationships** - Document why certain values work (e.g., step=17 avoids common bombing intervals)
3. **Track tradeoffs** - Changes that improve one matchup may harm another
4. **Hypothesis-driven changes** - Before each modification, state the expected outcome

**Key parameters to tune:**
- Step size for bombers/scanners (affects coverage pattern)
- Gate position for imp defenses
- Number of SPL instructions (affects process count vs. speed)
- Starting offset from main code

### Phase 6: Debugging Failures

When a warrior consistently loses to an opponent:

1. **Profile the failure** - Use pmars debugging to watch the battle:
   ```bash
   pmars -b -r 1 warrior.red opponent.red
   ```
2. **Identify failure mode** - Is the warrior being bombed, captured, out-replicated, or core-cleared?
3. **Trace causation** - At what point in the battle does the warrior lose control?
4. **Develop targeted fix** - Address the specific failure mechanism, not symptoms

### Phase 7: Multi-Opponent Optimization

When facing different win rate requirements:

1. **Prioritize high-threshold opponents** - Focus more effort on 75% targets than 33% targets
2. **Consider specialized warriors** - Sometimes separate warriors per opponent outperform one universal warrior
3. **Identify compatible strategies** - Find approaches that don't harm each other
4. **Accept strategic tradeoffs** - A warrior optimized for hard targets may sacrifice performance on easy targets

## Common Pitfalls

### Mistakes to Avoid

1. **Ad-hoc parameter changes** - Changing values without clear hypotheses leads to random walks
2. **Ignoring opponent code** - Reading behavior isn't understanding; examine the actual source
3. **Over-engineering early** - Complex multi-component warriors obscure what works and what doesn't
4. **Neglecting hardest opponents** - Easy wins don't compensate for failing required thresholds
5. **Batch testing** - Test after EVERY change to understand impact immediately
6. **Syntax/spacing issues** - Redcode assemblers are sensitive; verify syntax with dry runs
7. **Copying without understanding** - Adapting code from examples requires understanding why it works

### Red Flags During Development

- Making changes without being able to explain expected improvement
- Win rate oscillating without trending upward
- Spending most time on already-passing matchups
- Not using debugging tools to understand failures
- Submitting warriors that don't meet all thresholds

## Verification Checklist

Before considering warrior complete:

- [ ] All opponents analyzed and weaknesses documented
- [ ] Win rates meet or exceed ALL required thresholds
- [ ] Tested with statistically significant round counts (100+)
- [ ] Parameter choices can be justified with reasoning
- [ ] Failure modes against difficult opponents understood
- [ ] No syntax errors or assembly warnings

## Resources

### scripts/

Contains `test_warrior.sh` - An automated test script that runs battles against all opponents and reports results in a consistent format. Use this for every iteration to track progress systematically.

### references/

Contains `corewars_strategies.md` - Reference documentation covering CoreWars warrior archetypes, common patterns, and known effective techniques. Consult this before implementing unfamiliar strategies.