SirRoboGarage/.claude/commands/nim.md

name, description

name	description
nim-mcp-tools	Use for Nim symbol navigation, diagnostics, and type resolution. MANDATORY: Use specialized MCP tools (nimFindSymbols, nimFindReferences, nimListSymbols, nimCheckFile, nimCheckProject, nimFindTypeDefinition) first; fall back to grep only on error or user confirmation.

Nim MCP Tools

Core Mandate

AI agents MUST prefer specialized MCP tools over general-purpose instruments (grep, shell commands, read_file with manual parsing) for all Nim symbol-related and Nim diagnostics tasks. This is critical for:

1. Token Efficiency: MCP tools return structured, relevant data, avoiding large file reads or noisy grep outputs.
2. Precision: These tools understand Nim semantics (scopes, imports, overloads) which string-based search cannot.

Activation Rule

If the user asks to find, rename, remove, audit, update, standardize naming, or fix issues/project of a Nim symbol or its usages, this skill MUST be used first and the workflow must start with the Nim MCP symbol tools.

If the user asks to check a single Nim file for errors, warnings, hints, diagnostics, issues, problems, or compiler feedback, this skill MUST be used first and the workflow must start with nimCheckFile.

If the user asks to check a Nim project for errors, warnings, hints, diagnostics, issues, problems, compiler feedback, or to "fix" it, this skill MUST be used first and the workflow must start with nimCheckProject.

If the user asks to determine where a symbol comes from, what type it is, what its fields are (including private ones), or resolve a symbol's type definition, this skill MUST be used first and the workflow must start with nimFindTypeDefinition.

This applies to requests phrased as:

• "find all usages/references of Foo"
• "remove all definitions of and references to Foo"
• "rename Foo everywhere"
• "standardize naming for Foo"
• "fix casing for all variables"
• "where is Foo defined?"
• "list the symbols in this Nim file/module"
• "check this file/module for errors"
• "show diagnostics for foo.nim"
• "check this project/workspace/repository/package for errors"
• "fix issues in this project"
• "fix the repo"
• "find Nim diagnostics in the current codebase"
• "show warnings and hints for this repo"
• "scan the current module tree for Nim issues"
• "what is the type of this symbol?"
• "what module/package does this type come from?"
• "what fields does this type have?"
• "is this a type alias or a concrete type?"
• "where is this type defined?"

Treat user wording such as project, workspace, repository, repo, package, codebase, checkout, and module tree as referring to the current Nim project context when they are asking for project-wide diagnostics.

Treat user wording such as file, module (when a concrete Nim file is identified), source file, and explicit *.nim paths as referring to single-file diagnostics when they are asking for diagnostics for one file.

Do not pair nimFindSymbols, nimCheckFile, or nimCheckProject with grep, ripgrep, or shell search "just to double-check". If the task is about a Nim symbol or Nim diagnostics, MCP tools own the search unless they have already failed.

User Terminology vs MCP kind

Users may ask for symbol categories using looser or non-strict terminology. AI agents MUST map that wording to the exact Nim MCP kind values before filtering results from nimListSymbols(...) or nimFindSymbols(...).

The MCP server returns Nim-oriented kind names derived from nimsuggest symbol kinds with the leading sk removed, such as Const, EnumField, Field, Iterator, Converter, Let, Macro, Method, Proc, Template, Type, Var, and Func.

Use these terminology mappings when interpreting user requests:

• function / functions: usually match Func and Proc
• pure function / pure functions: match Func
• callable / routine: may include Func, Proc, Method, Iterator, Converter, Macro, and Template
• class / classes: match Type
• variable / variables: match Var and Let
• property / properties: match Field
• enum member / enum members: match EnumField
• constant / constants: match Const

When to Use

• Finding References: To rename a symbol, update a signature, or find usages.
• Symbol Discovery: To find where a symbol is defined by name.
• Type Resolution: To determine where a local symbol comes from (which module), what its type is, and what fields it has (including private ones).
• Naming Standardization: To fix casing or follow style guides across the project.
• Fixing Project Issues: To iteratively find and resolve all diagnostics in the project.
• File Analysis: To get an overview of all symbols in a file.
• File Diagnostics: To check one specific Nim file for errors, warnings, and hints.
• Project Diagnostics: To check the current Nim project for errors, warnings, and hints.
• Debugging Type Mismatches: When a diagnostic reveals a type mismatch, use nimFindTypeDefinition on both sides.
• Code Generation / Refactoring: Before generating code that interacts with a type, find its definition.

Workflows

1. Find All References or Usages of a Symbol Name

Do NOT grep for the name.

1. Call nimFindSymbols(query: "SymbolName") to get exact path, line, and column.
2. For each relevant result, call nimFindReferences(path, line, column).
3. Aggregate the results.

2. List All Symbols in a File

Do NOT read the whole file to find definitions.

1. Call nimListSymbols(path: "path/to/file.nim").
2. If the user asked for a symbol category, filter by the MCP kind values.
3. Use the returned list to navigate or analyze the file structure.

3. Find Definitions

1. Call nimFindSymbols(query: "query").

4. Resolve Type / Determine Origin of a Symbol

1. Call nimFindTypeDefinition(path, line, column) with the cursor positioned on the symbol of interest.
2. The result contains the definition path, line, column, name, type, and kind.
3. If the user needs to see the full definition, read the source at the returned path/line.

5. Debug Type Mismatch (Check + Type Definition)

1. Call nimCheckFile(path) to get the diagnostic with the exact error location.
2. For the reported location, call nimFindTypeDefinition(path, line, column) on the involved symbols.
3. Resolve the mismatch with the correct type or conversion.

6. Explore Object Structure (List Symbols + Type Definition)

1. Call nimFindSymbols(query: "TypeName") to locate the type definition.
2. Call nimFindTypeDefinition(path, line, column) on the type name to confirm the definition location.
3. Read the source at the definition location to enumerate all fields.

7. Check a Single Nim File for Diagnostics

1. Call nimCheckFile(path: "path/to/file.nim").
2. Treat the result as the answer unless the user explicitly asked for broader validation.
3. Use the returned diagnostics to report errors, warnings, and hints for that file.

8. Check the Current Nim Project for Diagnostics

1. Call nimCheckProject().
2. Use the returned diagnostics to report errors, warnings, and hints for the current Nim project context.

9. Standardize Naming

1. Iterate through the project files one by one.
2. For each file, call nimListSymbols(path: "path/to/file.nim").
3. For each symbol found, call nimFindReferences(path, line, column).
4. Standardize the definition and all identified reference sites to camelCase.
5. After a file has been processed, call nimCheckFile(path: "path/to/file.nim") to verify.

10. Fix Project Issues

1. Call nimCheckProject() to find all diagnostics in the project.
2. Analyze the diagnostics and resolve the identified issues.
3. Repeat steps 1 and 2 until nimCheckProject() returns no more issues.
4. Limit: If issues remain after 3 iterations, stop and prompt the user.
5. Post-Fix Step: Ask the user if they would like to check for naming consistency.

Fallback Policy

1. On Error: If an MCP tool fails due to a technical error, fall back to grep_search or other general-purpose tools. State clearly that the MCP tool failed.
2. On Empty Results: If an MCP tool returns no results, do NOT automatically fall back to grep. Prompt the user first.
3. Availability: If MCP tools are unavailable, use general-purpose tools but inform the user.

Critical Constraints

• NO GREP BY DEFAULT: Never use grep, ripgrep, or grep_search to find Nim symbols or references unless the MCP tools have explicitly errored out.
• PROMPT ON EMPTY: If MCP tools return nothing, ask the user before falling back to grep.
• NO MANUAL PARSING: Do not read large Nim files just to extract symbol locations; use nimListSymbols instead.
• NO DIY FILE CHECKS: Do not substitute manual inspection when nimCheckFile can return structured diagnostics.
• NO DIY PROJECT CHECKS: Do not substitute shelling out to ad-hoc Nim commands when nimCheckProject can return structured project diagnostics.
• TOKEN CONSERVATION: Minimize turns and context by using the most precise tool available.

Anti-Patterns

• Calling nimFindSymbols("Foo") and then running rg "Foo" anyway.
• Using rg for "find all usages" when nimFindReferences is available.
• Reading multiple Nim files to manually enumerate definitions that nimListSymbols can return directly.
• Reading a Nim file to manually search for a type definition when nimFindTypeDefinition can resolve it precisely.
• Grepping for type Foo* = instead of using nimFindTypeDefinition or nimFindSymbols.
• Running nimCheckProject() when the user asked to check one specific Nim file.
• Manually reading or building a single Nim file first when nimCheckFile can return structured diagnostics.
• Running a manual project build or grep-based log scan first when nimCheckProject is available.