commit 02ccc3eb714325a4e890135269877681a6afc1b4 (tree)
parent b16854aa44e7c1d044523f962ee8415d1db34922
Author: Motiejus Jakštys <motiejus@jakstys.lt>
Date: Fri, 13 Feb 2026 07:55:46 +0000
add skill
Diffstat:
1 file changed, 116 insertions(+), 0 deletions(-)
diff --git a/.claude/skills/port-astgen/SKILL.md b/.claude/skills/port-astgen/SKILL.md
@@ -0,0 +1,116 @@
+---
+name: port-astgen
+description: Iteratively port AstGen.zig to astgen.c by enabling skipped corpus tests, finding divergences, and mechanically copying upstream code.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
+disable-model-invocation: true
+---
+
+# Port AstGen — Iterative Corpus Test Loop
+
+You are porting `AstGen.zig` to `astgen.c`. This is a **mechanical
+translation** — no creativity, no invention. When the C code differs
+from Zig, copy the Zig structure into C.
+
+## Key files
+
+- `astgen.c` — C implementation (modify this)
+- `astgen_test.zig` — corpus tests (enable/skip tests here)
+- `~/code/zig/lib/std/zig/AstGen.zig` — upstream reference (~14k lines)
+- `~/code/zig/lib/std/zig/Ast.zig` — AST node accessors
+- `~/code/zig/lib/std/zig/Zir.zig` — ZIR instruction definitions
+
+## Loop
+
+Repeat the following steps until all corpus tests pass or you've made
+3 consecutive iterations with zero progress.
+
+### Step 1: Find the first skipped corpus test
+
+Search `astgen_test.zig` for lines matching:
+```
+if (true) return error.SkipZigTest
+```
+Pick the first one. If none found, all corpus tests pass — stop.
+
+### Step 2: Enable it
+
+Remove or comment out the `if (true) return error.SkipZigTest` line.
+
+### Step 3: Run tests
+
+```sh
+zig build test 2>&1
+```
+
+Record the output. If tests pass, go to Step 7.
+
+### Step 4: Analyze the failure
+
+From the test output, determine the failure type:
+
+- **`has_compile_errors`**: Temporarily add `#include <stdio.h>` and
+ `fprintf(stderr, ...)` to `setCompileError()` in `astgen.c` to find
+ which `SET_ERROR` fires. Run the test again and note the function and
+ line.
+- **`zir mismatch`**: Note `inst_len`, `extra_len`, `string_bytes_len`
+ diffs and the first tag mismatch position.
+- **`unhandled tag N`**: Add the missing ZIR tag to the `expectEqualData`
+ and `dataMatches` switch statements in `astgen_test.zig`.
+
+### Step 5: Compare implementations
+
+Find the upstream Zig function that corresponds to the failing code
+path. Use the Task tool with `subagent_type=general-purpose` to read
+both implementations and enumerate **every difference**.
+
+Focus on differences that affect output:
+- Extra data written (field order, conditional fields, body lengths)
+- Instruction tags emitted
+- String table entries
+- Break payload values (operand_src_node)
+
+Do NOT guess. Read both implementations completely and compare
+mechanically.
+
+### Step 6: Port the fix
+
+Apply the minimal mechanical change to `astgen.c` to match the upstream.
+Run `zig build test` after each change to check for progress.
+
+**Progress** means any of:
+- `inst_len` diff decreased
+- `extra_len` diff decreased
+- `string_bytes_len` diff decreased
+- First tag mismatch position moved later
+
+If after porting a fix the test still fails but progress was made,
+continue to Step 7 (commit progress, re-skip).
+
+### Step 7: Clean up and commit
+
+1. If the corpus test still fails: re-add the `SkipZigTest` line with
+ a TODO comment describing the remaining diff.
+2. Remove ALL `fprintf`/`printf` debug statements from `astgen.c`.
+3. Remove `#include <stdio.h>` if it was added for debugging.
+4. Verify: `zig build all` must exit 0 with no unexpected output.
+5. Commit:
+ ```sh
+ git add astgen.c astgen_test.zig
+ git commit -m "<descriptive message>
+
+ Co-Authored-By: <whatever model is running this>"
+ ```
+
+### Step 8: Repeat
+
+Go back to Step 1.
+
+## Rules
+
+- **Mechanical copy only.** Do not invent new approaches. If the
+ upstream does X, do X in C.
+- **Never remove zig-cache.**
+- **Never print to stdout/stderr in committed code.** Debug prints are
+ temporary only.
+- **Functions must appear in the same order as in the upstream Zig file.**
+- **Commit after every iteration**, even partial positive progress.
