# Aoc

> Use for Advent of Code, algorithm puzzles, competitive programming, or puzzle-solution optimization.

- Skill: `anntnzrb/aoc` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add anntnzrb/aoc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/anntnzrb/aoc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: AGPL-3.0-or-later
- Author: anntnzrb (https://skillmd.com/u/anntnzrb)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/anntnzrb/aoc

---


# Advent of Code Solver

Language-agnostic problem solving: TDD + correctness-first.

## Workflow

```
1. READ      → Study problem + examples (examples are your spec)
2. PARSE     → Extract data structures from input
3. TEST      → Write tests from example input/output
4. IMPLEMENT → Minimal code to pass
5. RUN       → Execute on real input
6. ADAPT     → Refactor for Part 2
```

## Solution Architecture

```
parse(input) → data structure
part1(data)  → answer
part2(data)  → answer
```

Parse once; solve both parts; test each function independently.

## Algorithm Selection

|Scenario|Algorithm|
|---|---|
|Unweighted shortest path|BFS|
|Path existence / exhaustive|DFS|
|Weighted shortest path|Dijkstra|
|Weighted + good heuristic|A\*|
|"After N iterations..." (huge N)|Cycle detection|
|"Find minimum X such that..."|Binary search|
|"Count ways..." / "Min/max..."|Dynamic programming|
|Connected regions|Flood fill|

Algorithms: [algorithms.md](cookbook/algorithms.md)

## Input Patterns

|Format|Approach|
|---|---|
|Numbers in text|Regex `-?\d+`|
|Grid of chars|2D array or dict by coords|
|Blank-line groups|Split on `\n\n` first|
|Key-value pairs|Parse into map/dict|
|Instructions/opcodes|Pattern match each line|

Grid coordinates: `(row, col)`, row↓; sparse dict for infinite/sparse grids.
Directions: `UP=(-1,0), DOWN=(1,0), LEFT=(0,-1), RIGHT=(0,1)`

Parsing: [parsing.md](cookbook/parsing.md)

## Part 2 Patterns

1. **Scale up** → Optimize algorithm
2. **Add dimensions** → 2D → 3D/4D
3. **Many iterations** → Find cycle, skip ahead
4. **Reverse question** → "Find X" → "Given X, find Y"
5. **Add constraints** → New rules or edge cases

## Debugging

- Print intermediate state at each step
- Compare with example walkthrough
- Add assertions for every assumption
- Test parsing separately from logic
- Binary search on input size to isolate failures

## Complexity Targets

|Input Size|Target|
|---|---|
|n ≤ 20|O(2^n) OK|
|n ≤ 500|O(n³) OK|
|n ≤ 10,000|O(n²) OK|
|n ≤ 1,000,000|O(n log n)|
|n > 1,000,000|O(n) or O(log n)|

## Research Tools

```
# gh search code for algorithm implementations
gh search code "heapq.heappush" --language=python   # Dijkstra/priority queue
gh search code "collections.deque" --language=python # BFS patterns
gh search code "fn dijkstra" --language=rust
```

## Required follow-up reads

|Need|Read|When|
|---|---|---|
|Algorithm recipes|`cookbook/algorithms.md`|When selecting or implementing graph, DP, cycle, or search algorithms|
|Parsing recipes|`cookbook/parsing.md`|For grids, grouped input, coordinates, hex grids, or irregular text|
|General design reference|`reference.md`|For data structures, optimization, Part 2 adaptation, or anti-patterns|