notjack.space
AI agent skill files related to programming with Racket
Add Resyntax skill
+197
resyntax/SKILL.md
+197
resyntax/SKILL.md
···
···
1
+
---
2
+
name: resyntax
3
+
description: "Use this skill whenever running Resyntax to analyze or refactor Racket code. Triggers include: any mention of 'resyntax', 'refactoring' in a Racket context, requests to find idiomatic improvements in Racket code, or requests to clean up or modernize Racket code. Also use when the user asks to run linting or style checks on Racket files."
4
+
---
5
+
6
+
# Resyntax
7
+
8
+
## Overview
9
+
10
+
Resyntax is a refactoring tool for Racket. It analyzes Racket code and suggests
11
+
idiomatic improvements, powered by `syntax-parse`-based refactoring rules. Use
12
+
it to find and automatically apply refactorings such as removing legacy API
13
+
calls, simplifying expressions, and modernizing code style.
14
+
15
+
Resyntax has two modes: **analyze** (report suggestions) and **fix** (apply
16
+
changes to files directly).
17
+
18
+
---
19
+
20
+
## Running Resyntax
21
+
22
+
Resyntax is a *launcher*, not a `raco` command. Run it as `resyntax`, NOT
23
+
`raco resyntax`.
24
+
25
+
```sh
26
+
# Analyze a single file (report suggestions without modifying anything)
27
+
resyntax analyze --file path/to/file.rkt
28
+
29
+
# Analyze all files in a directory
30
+
resyntax analyze --directory path/to/project/
31
+
32
+
# Analyze an installed package
33
+
resyntax analyze --package my-package
34
+
35
+
# Analyze only files changed relative to a Git branch
36
+
resyntax analyze --local-git-repository . origin/main
37
+
```
38
+
39
+
### Applying fixes
40
+
41
+
Use `resyntax fix` to apply suggested changes directly to files. **Always prefer
42
+
`resyntax fix` over manually reproducing suggestions.** This ensures changes are
43
+
exactly what Resyntax intended and makes auditing easier.
44
+
45
+
```sh
46
+
# Fix a single file
47
+
resyntax fix --file path/to/file.rkt
48
+
49
+
# Fix all files in a directory
50
+
resyntax fix --directory path/to/project/
51
+
52
+
# Fix an installed package
53
+
resyntax fix --package my-package
54
+
55
+
# Fix only files changed relative to a Git branch
56
+
resyntax fix --local-git-repository . origin/main
57
+
```
58
+
59
+
---
60
+
61
+
## Workflow: Using Resyntax to refactor code
62
+
63
+
Follow this workflow when using Resyntax to improve code quality:
64
+
65
+
### Step 1: Analyze to find suggestions
66
+
67
+
Run `resyntax analyze` first to see what Resyntax would change, without
68
+
modifying any files. Review the output to understand the suggestions.
69
+
70
+
```sh
71
+
resyntax analyze --file path/to/file.rkt
72
+
```
73
+
74
+
Output looks like:
75
+
76
+
```
77
+
resyntax: path/to/file.rkt:43:5 [rule-name]
78
+
79
+
Description of the suggested change.
80
+
81
+
43 (original-code ...)
82
+
83
+
43 (suggested-replacement ...)
84
+
```
85
+
86
+
Each suggestion includes:
87
+
- The file, line, and column
88
+
- The rule name in brackets (e.g. `[syntax-protect-migration]`)
89
+
- A description of why the change is suggested
90
+
- The original code and the replacement
91
+
92
+
### Step 2: Apply fixes with `resyntax fix`
93
+
94
+
Once you've reviewed the suggestions and they look appropriate, use
95
+
`resyntax fix` to apply them:
96
+
97
+
```sh
98
+
resyntax fix --file path/to/file.rkt
99
+
```
100
+
101
+
Resyntax modifies files in place. It may run multiple passes, since applying one
102
+
fix can unlock further fixes.
103
+
104
+
### Step 3: Run tests to verify
105
+
106
+
Always run the project's tests after applying fixes:
107
+
108
+
```sh
109
+
raco test path/to/file.rkt
110
+
```
111
+
112
+
### Step 4: Review the diff
113
+
114
+
Check what Resyntax actually changed:
115
+
116
+
```sh
117
+
git diff
118
+
```
119
+
120
+
This lets you (and reviewers) confirm the changes are correct before committing.
121
+
122
+
---
123
+
124
+
## Useful options
125
+
126
+
### Limiting scope
127
+
128
+
```sh
129
+
# Apply at most N fixes
130
+
resyntax fix --file foo.rkt --max-fixes 5
131
+
132
+
# Modify at most N files
133
+
resyntax fix --directory src/ --max-modified-files 3
134
+
135
+
# Modify at most N lines total
136
+
resyntax fix --directory src/ --max-modified-lines 50
137
+
```
138
+
139
+
### Targeting specific rules
140
+
141
+
```sh
142
+
# Only analyze with a specific refactoring rule
143
+
resyntax analyze --file foo.rkt --refactoring-rule if-else-false-to-and
144
+
145
+
# Only fix with a specific refactoring rule
146
+
resyntax fix --file foo.rkt --refactoring-rule syntax-protect-migration
147
+
```
148
+
149
+
### Timeouts
150
+
151
+
The default analyzer timeout is 10 seconds per analyzer per file. Increase it
152
+
for files that are slow to expand:
153
+
154
+
```sh
155
+
resyntax analyze --file foo.rkt --analyzer-timeout 30000
156
+
```
157
+
158
+
### Git integration
159
+
160
+
The `--local-git-repository` option is useful for analyzing only files that have
161
+
been modified in a branch:
162
+
163
+
```sh
164
+
resyntax analyze --local-git-repository /path/to/repo origin/main
165
+
```
166
+
167
+
### Output formats for `resyntax fix`
168
+
169
+
```sh
170
+
# Output a commit message summarizing fixes to stdout
171
+
resyntax fix --file foo.rkt --output-as-commit-message
172
+
173
+
# Output results as JSON
174
+
resyntax fix --file foo.rkt --output-as-json
175
+
176
+
# Create individual Git commits for each fix
177
+
resyntax fix --directory src/ --create-multiple-commits
178
+
```
179
+
180
+
---
181
+
182
+
## Important: always use `resyntax fix`, not manual edits
183
+
184
+
When applying Resyntax suggestions, **always use `resyntax fix`** to apply
185
+
changes rather than manually editing files to match the suggestion output. This
186
+
is important because:
187
+
188
+
1. It guarantees the applied change exactly matches what Resyntax computed.
189
+
2. It eliminates the risk of introducing typos or subtle differences when
190
+
reproducing suggestions by hand.
191
+
3. It makes code review easier — reviewers can trust that the diff came from the
192
+
tool itself.
193
+
194
+
The only reason to manually edit would be if `resyntax fix` fails on a specific
195
+
file (e.g., due to expansion errors) but `resyntax analyze` was able to show the
196
+
suggestion. In that case, note in the commit message that the change was applied
197
+
manually based on a Resyntax suggestion.