# Writing Hashql Diagnostics

> Writing Hashql Diagnostics is an Agent Skill for development published in the hashintel/hash repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

- Skill name: `writing-hashql-diagnostics`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/hashintel/hash/blob/HEAD/.claude/skills/writing-hashql-diagnostics/SKILL.md
- Repository: hashintel/hash (1,615 GitHub stars when collected)

## SKILL.md

# HashQL Diagnostic Writing

Provides HASH-specific patterns for writing high-quality diagnostics using the `hashql-diagnostics` crate, ensuring messages are helpful, actionable, and follow consistent style conventions.

## Core Principles

**Diagnostics should be helpful, not just correct:**

✅ **DO:**

- Start messages with lowercase
- Use backticks for code elements: `` expected `bool`, found `String` ``
- Make messages actionable and specific
- Use "invalid" not "illegal"
- Keep help messages as imperatives: "add type annotations"

❌ **DON'T:**

- End messages with punctuation (unless multi-sentence)
- Use apologetic language ("sorry", "unfortunately")
- Write vague messages ("something went wrong")
- Capitalize message starts (unless code identifier)

## Quick Reference

### Creating a Diagnostic

```rust
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 Levels

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

### Message Style

```rust
// ✅ 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
```

### Adding Suggestions

```rust
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)
);
```

## References

- [Comprehensive guidelines](references/guidelines.md) - Complete message style guide, span selection, category design, label usage, help vs note, suggestion quality, review checklist
- [HashQL testing skill](../testing-hashql/SKILL.md) - For compiletest coverage

---

Source: https://www.openparable.com/skill/development/writing-hashql-diagnostics (OpenParable). Cite the canonical URL above.
