agentleFS
robmclartyrobmclarty/trailhead/.claude/skills/mine-ast-grep-rules/SKILL.md

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.

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
  1. Distinctive:

    Before a release or planning session, as a repo-health sweep

    line 17
  2. Distinctive:

    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 …

    line 33
  3. Very specific:

    Read docs/lessons.md end-to-end: Don't skim. Build a flat list of entries — each one gets a short key describing the code-level pattern …

    line 37
  4. Very specific:

    Read every rule under tools/ast-grep/rules/ (titles and rule: blocks are enough)

    line 40
  5. Very specific:

    Write a mining report: Create docs/decisions/<next-number>-rule-mining-<date>.md summarizing:

    line 52
  6. Very specific:

    Run pnpm check:full: Every drafted rule plus its fix entry must pass the pipeline.

    line 59
  7. Distinctive:

    Don't invent patterns: If the lessons don't support a rule, don't write it.

    line 65

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-rule directly
  • 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

  1. Read docs/lessons.md end-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").
  2. Check what's already enforced.
    • Read every rule under tools/ast-grep/rules/ (titles and rule: blocks are enough)
    • pnpm exec oxlint --rules for oxlint coverage
    • Drop any pattern from your list that's already caught
  3. 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.
  4. 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 (see docs/conventions.md#ast-grep-rule-message-format), same use of the ast-grep MCP 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.
  5. Preview real hits. Run find_code_by_rule (or pnpm 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 to severity: warning or move it to the watch list with a note.
  6. 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.
  7. Write a mining report. Create docs/decisions/<next-number>-rule-mining-<date>.md summarizing:
    • 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
  8. 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.
  9. 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_rule keeps the loop in-conversation; the playground tab-switching friction leads to untested rules.

Output shape

The skill's deliverable is two artifacts:

  1. Rule files under tools/ast-grep/rules/ (one per cluster meeting the threshold)
  2. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.