mine-ast-grep-rules
Skill0 starsChanged 7 months agoMITView on GitHub
Mine docs/lessons.md for recurring patterns and draft candidate ast-grep rules from them. Use when the lessons log has grown since the last mining pass and you want to promote repeat-offender patterns into enforced rules. Complements propose-ast-grep-rule by surfacing which rules are worth writing in the first place.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- add-browser-mcpSkill
- add-packageSkill
- add-visual-lintingSkill
- post-friction-lessonSkill
- propose-ast-grep-ruleSkill
- versionSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
Before a release or planning session, as a repo-health sweep
- Distinctive: line 33
If a pattern is real but under the threshold, note it in the output as a watch — a candidate to re-evaluate next pass — rather than …
- Very specific: line 37
Read
docs/lessons.mdend-to-end: Don't skim. Build a flat list of entries — each one gets a short key describing the code-level pattern … - Very specific: line 40
Read every rule under tools/ast-grep/rules/ (titles and rule: blocks are enough)
- Very specific: line 52
Write a mining report: Create docs/decisions/<next-number>-rule-mining-<date>.md summarizing:
- Very specific: line 59
Run
pnpm check:full: Every drafted rule plus its fix entry must pass the pipeline. - Distinctive: line 65
Don't invent patterns: If the lessons don't support a rule, don't write it.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
mine-ast-grep-rules
Reads docs/lessons.md, clusters recurring friction patterns, drafts ast-grep rules for the ones that repeat, tests those rules against the repo via the ast-grep MCP, and opens a PR with the candidates.
This skill is the batch counterpart to propose-ast-grep-rule. Use propose-ast-grep-rule when you hit a pattern in the moment; use this skill periodically to catch patterns that slipped through because no single occurrence felt rule-worthy.
When to use this skill
- The lessons log has grown ≥5 entries since the last mining pass
- You notice the same
**Potential next step:** - [ ] rule: …checkbox appearing in multiple lessons - Before a release or planning session, as a repo-health sweep
When NOT to use this skill
- The lessons file is short (<10 entries total) — not enough signal
- You just added one lesson and know exactly which rule to write — use
propose-ast-grep-ruledirectly - The recurring pattern is a style issue the formatter would catch
The three-evidence threshold
This skill only promotes a candidate to a drafted rule when at least three historical lessons describe the same pattern. Two is a coincidence; three is a pattern worth a structural check. Lessons count toward the threshold if they:
- Describe the same code-level anti-pattern (not the same tool or the same config issue — those need doc or structure fixes, not rules)
- Would plausibly be caught by a single YAML rule (ast-grep's matching model)
- Aren't already covered by an existing rule in
tools/ast-grep/rules/or by an oxlint rule
If a pattern is real but under the threshold, note it in the output as a watch — a candidate to re-evaluate next pass — rather than drafting the rule now.
Steps
- Read
docs/lessons.mdend-to-end. Don't skim. Build a flat list of entries — each one gets a short key describing the code-level pattern (e.g. "direct console.log in packages/", "class used for stateful helper", "relative import across package"). - Check what's already enforced.
- Read every rule under
tools/ast-grep/rules/(titles andrule:blocks are enough) pnpm exec oxlint --rulesfor oxlint coverage- Drop any pattern from your list that's already caught
- Read every rule under
- Cluster. Group lessons by pattern key. Count occurrences per cluster. A cluster earns a draft if count ≥3. Everything else goes on the watch list.
- For each qualifying cluster, draft a rule. Follow the steps in
.claude/skills/propose-ast-grep-rule/SKILL.md— same YAML shape, same message format (seedocs/conventions.md#ast-grep-rule-message-format), same use of theast-grepMCP for AST dumping and match verification. The only difference: you're processing a batch, so keep each draft to a single file and defer cross-cutting refactors. - Preview real hits. Run
find_code_by_rule(orpnpm exec ast-grep scan --rule-id <id>) for each draft. If a rule fires on >20 existing sites, pause — either the rule is too broad, or the codebase has a genuine compliance gap that needs an explicit fix-up commit. Either way, don't steamroll the repo from a mining pass; downgrade the rule toseverity: warningor move it to the watch list with a note. - Add fix entries. For each drafted rule, add an entry to
tools/check/fixes.ts— one-line fix exemplar, docs anchor. This is what the normalized diagnostic stream (ADR 0002) uses. - Write a mining report. Create
docs/decisions/<next-number>-rule-mining-<date>.mdsummarizing:- Lessons read (count + range of dates)
- Clusters found, with counts
- Rules drafted (with ids)
- Watch list (clusters below the threshold)
- Any existing rule that the mining suggests should be tightened or split
- Run
pnpm check:full. Every drafted rule plus its fix entry must pass the pipeline. If a rule breaks existing code, either fix the code in the same PR or downgrade the rule. - Open a PR. One PR for the whole mining pass — reviewers can approve rules independently by cherry-picking if needed, but the mining report ties them together. Title:
mine-rules: <N> new ast-grep rules from lessons. Body: link to the report.
Guardrails
- Don't invent patterns. If the lessons don't support a rule, don't write it. The three-evidence threshold is not optional.
- Don't mine the same lesson twice. Track which entries have contributed to a rule by citing them in the rule's
note:block. Future mining passes should skip already-cited lessons. - Don't batch-commit code fixes. Rules from a mining pass are the change. If existing code violates a new rule, fix the code in a follow-up commit (or PR) so the rule addition stays reviewable.
- Use the MCP for verification, not the playground.
test_match_code_rulekeeps the loop in-conversation; the playground tab-switching friction leads to untested rules.
Output shape
The skill's deliverable is two artifacts:
- Rule files under
tools/ast-grep/rules/(one per cluster meeting the threshold) - Mining report ADR under
docs/decisions/— documents the pass, the clusters, the watch list
Plus the corresponding PR. That's it — no config tweaks, no workflow changes, no speculative tooling. If the mining pass surfaces a need for new infrastructure, log that as a lesson and come back to it next cycle.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

