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

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

Part 2 Patterns

Scale up → Optimize algorithm
Add dimensions → 2D → 3D/4D
Many iterations → Find cycle, skip ahead
Reverse question → "Find X" → "Given X, find Y"
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|