agentleFS
MicrosoftKnown publishermicrosoft/SqlScriptDOM/.agents/skills/verify-and-test-tsql-syntax/SKILL.md

verify-and-test-tsql-syntax

Skill284 starsChanged 7 months agoMITView on GitHub

Verify whether an exact T-SQL script is already supported by SqlScriptDOM, then add or update the correct parser tests and baselines. Use when a user asks if syntax already works, or when adding regression coverage for a specific script.

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. About 0 are common, 16 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈16

    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:

    Do not use it for broad feature design.

    line 17
  2. Distinctive:

    Always verify the exact T-SQL text first, character for character.

    line 25
  3. Distinctive:

    Do not create standalone console apps, ad hoc parsers, or extra test projects.

    line 27
  4. Very specific:

    After verification, add proper test coverage through TestScripts, baselines, and the existing syntax test classes.

    line 28
  5. Distinctive:

    Remove any temporary debug-only test methods once the result is confirmed.

    line 29
  6. Distinctive:

    If the user has not supplied the exact script yet, stop and request it before continuing.

    line 40
  7. Distinctive:

    Add a temporary debug unit test method to the appropriate existing test class and test the exact script as provided.

    line 44
  8. Distinctive:

    If parsing succeeds, move directly to comprehensive test coverage.

    line 54
  9. Distinctive:

    If parsing fails, capture the exact parse errors and classify the failure.

    line 55
  10. Distinctive:

    Use the failure mode to route the next step:

    line 59
  11. Distinctive:

    When similar syntax already works in another context, prefer validation analysis before changing grammar.

    line 64
  12. Distinctive:

    After verification, create or update the proper permanent tests using the existing framework:

    line 68
  13. Very specific:

    Add the input script under Test/SqlDom/TestScripts/.

    line 70
  14. Very specific:

    Add the matching baseline under Test/SqlDom/Baselines<version>/.

    line 71
  15. Very specific:

    Add the ParserTest entry or permanent test method in the correct Only<version>SyntaxTests.cs file.

    line 72
  16. Distinctive:

    Run validation in this order:

    line 86
  17. Distinctive:

    If the targeted test fails because of a baseline mismatch:

    line 93
  18. Distinctive:

    use the generated output from the failure log to update the baseline

    line 94
  19. Distinctive:

    only then run the full suite

    line 96
  20. Distinctive:

    Use these repo paths when doing the work:

    line 100

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

Overview

This skill determines whether a specific T-SQL script is already supported and then guides the follow-up testing work.

Use it for:

  • verifying whether a script already parses
  • confirming which parser version should support the syntax
  • adding or updating regression coverage in the existing ScriptDOM test framework

Do not use it for broad feature design. If the verification shows missing parser support, route the implementation work to the appropriate repo instruction:

  • bug_fixing.guidelines.instructions.md
  • grammar_validation.guidelines.instructions.md
  • parser.guidelines.instructions.md
  • testing.guidelines.instructions.md

Core Rules

  • Always verify the exact T-SQL text first, character for character.
  • For first-pass verification, add a debug unit test method to an existing test file such as Only180SyntaxTests.cs when the syntax targets vNext or the latest parser.
  • Do not create standalone console apps, ad hoc parsers, or extra test projects.
  • After verification, add proper test coverage through TestScripts, baselines, and the existing syntax test classes.
  • Remove any temporary debug-only test methods once the result is confirmed.

Workflow

1. Gather the minimum inputs

Ask for:

  • the exact T-SQL script to verify
  • the SQL Server version or parser version expected to support it
  • the current behavior and the expected behavior

If the user has not supplied the exact script yet, stop and request it before continuing.

2. Verify the exact script first

Add a temporary debug unit test method to the appropriate existing test class and test the exact script as provided.

Use this sequence:

dotnet build SqlScriptDom/Microsoft.SqlServer.TransactSql.ScriptDom.csproj -c Debug
dotnet test --filter "DebugExactScriptTest" Test/SqlDom/UTSqlScriptDom.csproj -c Debug

Verification expectations:

  • If parsing succeeds, move directly to comprehensive test coverage.
  • If parsing fails, capture the exact parse errors and classify the failure.

3. Classify the gap if verification fails

Use the failure mode to route the next step:

  • Grammar issue: parser does not recognize the syntax at all.
  • Validation issue: syntax parses but is rejected as unsupported or invalid in context.
  • Predicate recognition issue: identifier-based predicate fails in parentheses.

When similar syntax already works in another context, prefer validation analysis before changing grammar.

4. Add comprehensive coverage

After verification, create or update the proper permanent tests using the existing framework:

  • Add the input script under Test/SqlDom/TestScripts/.
  • Add the matching baseline under Test/SqlDom/Baselines<version>/.
  • Add the ParserTest entry or permanent test method in the correct Only<version>SyntaxTests.cs file.
  • Preserve the exact user syntax in the test script before adding broader coverage.

Determine the parser version using the repo mapping:

  • SQL Server 2014 -> TSql120
  • SQL Server 2016 -> TSql130
  • SQL Server 2017 -> TSql140
  • SQL Server 2019 -> TSql150
  • SQL Server 2022 -> TSql160
  • SQL Server 2025 -> TSql170
  • SQL Server vNext/latest -> TSql180

5. Validate the testing slice

Run validation in this order:

dotnet test --filter "FullyQualifiedName~YourFeatureTest" Test/SqlDom/UTSqlScriptDom.csproj -c Debug
dotnet test Test/SqlDom/UTSqlScriptDom.csproj -c Debug

If the targeted test fails because of a baseline mismatch:

  • use the generated output from the failure log to update the baseline
  • rerun the same targeted test
  • only then run the full suite

File Targets

Use these repo paths when doing the work:

  • Grammar files: SqlScriptDom/Parser/TSql/TSql*.g
  • AST definition: SqlScriptDom/Parser/TSql/Ast.xml
  • Validation code: SqlScriptDom/Parser/TSql/TSql80ParserBaseInternal.cs
  • Test scripts: Test/SqlDom/TestScripts/
  • Baselines: Test/SqlDom/Baselines<version>/
  • Syntax tests: Test/SqlDom/Only<version>SyntaxTests.cs

Completion Checklist

  • Verified the exact script first in an existing test file
  • Classified the result as already supported or missing support
  • Added or updated permanent test coverage in the standard test framework
  • Preserved the exact user syntax in the new test script
  • Ran targeted validation for the touched test slice
  • Ran the full UTSqlScriptDom suite before finishing

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.