// HashQL diagnostic writing patterns using hashql-diagnostics crate. Use when creating error messages, warnings, Labels, Messages, Severity levels, Patches, Suggestions, or improving diagnostic quality in HashQL code.
| name | writing-hashql-diagnostics |
| description | HashQL diagnostic writing patterns using hashql-diagnostics crate. Use when creating error messages, warnings, Labels, Messages, Severity levels, Patches, Suggestions, or improving diagnostic quality in HashQL code. |
| license | AGPL-3.0 |
| metadata | {"triggers":{"type":"domain","enforcement":"suggest","priority":"high","keywords":["diagnostic","hashql-diagnostics","Label","Message","Severity","Patch","Suggestions"],"intent-patterns":["\\b(create|write|add|improve)\\b.*?\\bdiagnostic\\b","\\b(error|warning)\\b.*?\\bmessage\\b"]}} |
Provides HASH-specific patterns for writing high-quality diagnostics using the hashql-diagnostics crate, ensuring messages are helpful, actionable, and follow consistent style conventions.
Diagnostics should be helpful, not just correct:
✅ DO:
expected `bool`, found `String`❌ DON'T:
use hashql_diagnostics::{Diagnostic, Label, Message, Severity};
let mut diagnostic = Diagnostic::new(category, Severity::Error)
.primary(Label::new(span, "expected `bool`, found `String`"));
diagnostic.add_label(Label::new(other_span, "expected because of this"));
diagnostic.add_message(Message::help("try using a comparison"));
| Severity | When to Use |
|---|---|
Bug | Internal compiler error |
Fatal | Unrecoverable error |
Error | Must be fixed to compile |
Warning | Suspicious code to review |
Note | Informational context |
// ✅ Good
"cannot find variable `count` in this scope"
"expected `;` after expression"
// ❌ Bad
"Error: Variable not found." // capitalized, punctuation
"Sorry, there's a type mismatch" // apologetic
use hashql_diagnostics::{Message, Patch, Suggestions};
let suggestion = Suggestions::patch(Patch::new(span, "corrected_code"));
diagnostic.add_message(
Message::help("fix the typo").with_suggestions(suggestion)
);
Use when creating, moving, splitting, or organizing TypeScript files and folders. Applies fractal tree file-structuring rules which reduce the cognitive overhead of choosing where to put files and ultimately navigating a codebase (once the structure is established and understood).
HashQL testing strategies including compiletest (UI tests), unit tests, and snapshot tests. Use when writing tests for HashQL code, using //~ annotations, running --bless, debugging test failures, or choosing the right testing approach.
Rust documentation practices for HASH codebase. Use when writing doc comments, documenting functions/types/traits/modules, creating error sections, using intra-doc links, or following rustdoc conventions.
HASH error handling patterns using error-stack crate. Use when working with Result types, Report types, defining custom errors, propagating errors with change_context, adding context with attach, implementing Error trait, or documenting error conditions in Rust code.
Guide for creating effective Agent Skills. Use when users want to create a new skill (or update an existing skill) that extends an AI agent's capabilities with specialized knowledge, workflows, or tool integrations. Covers skill structure, YAML frontmatter, trigger configuration, and the 500-line rule.
HashQL J-Expr syntax for writing queries. Use when writing J-Expr code, using #literal/#struct/#list constructs, understanding function call syntax, or working with HashQL query files (.jsonc).