Skip to content
Skills Library
Programming · Analysis

debug-formatter

/debug-formatter

Debug a SQL formatter bug. Use when the user reports incorrect formatting, such as wrong whitespace, misplaced comments, or blank lines.

Repository
syntaqlite ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Debug a SQL formatter bug. Use when the user reports incorrect formatting, such as wrong whitespace, misplaced comments, or blank lines.

Original author description

Debug a SQL formatter bug. Use when the user reports incorrect formatting, such as wrong whitespace, misplaced comments, or blank lines.

How it works

  1. Instructions
Original SKILL.md headings · 57 lines, 355 words
SKILL.md preview
---
name: debug-formatter
description: Debug a SQL formatter bug. Use when the user reports incorrect formatting, such as wrong whitespace, misplaced comments, or blank lines.
user_invocable: true
---

# debug-formatter

Debug a SQL formatter bug using red-green testing and pipeline tracing.

## Instructions

### 1. Reproduce (RED)

Add a failing test to `syntaqlite/tests/fmt_comments.rs` (comment bugs) or the
relevant `tests/fmt_diff_tests/*.py` file. Always `eprintln!` the actual output:

```rust
#[test]
fn descriptive_name() {
    let input = "...";
    let out = fmt(input);
    eprintln!("=== actual ===\n{out}=== end ===");
    assert_eq!(out, "...\n");
}
```

Run it and confirm RED:
```sh
cargo test -p syntaqlite --features fmt,sqlite --test fmt_comments TEST_NAME -- --nocapture
```

### 2. Trace the pipeline

Work through these layers to find the root cause:

| Layer | File | What to check |
|-------|------|---------------|
| Grammar | `syntaqlite-buildtools/parser-nodes/*.synq` | `fmt { }` block; `clause("KW", field)` expands to `IF_SET → LINE → KEYWORD → NEST(LINE, CHILD)` |
| Bytecode compiler | `syntaqlite-buildtools/src/dialect_codegen/fmt_compiler.rs` | How `Fmt::Clause`, `Fmt::Keyword` compile to opcodes |
| Interpreter | `syntaqlite/src/fmt/interpret.rs` | Main loop in `interpret_node`; state = `running` (committed doc) + `pending` (deferred line breaks) |
| Comment drain | `syntaqlite/src/fmt/comment.rs` | `drain_before(offset)` respects `has_non_comment_text` guard; `drain_keyword_interior()` skips it for multi-word keywords |
| flush_drain | `interpret.rs` | Integrates `DrainResult { trailing, leading }` into running/pending; when `leading != NIL`, pending is dropped |
| Doc renderer | `syntaqlite/src/fmt/doc.rs` | Wadler-style; `hardline` always breaks, `line` breaks if group broken |

### 3. Common bug patterns

- **Blank line between comments**: Two consecutive drains both produce `hardline + comment + hardline`; back-to-back hardlines = blank line. Fix via `continuation` flag on `drain_keyword_interior`.
- **Comment on wrong side of keyword**: `flush_drain` for interior comments runs before keyword text is emitted. Check flush vs keyword append ordering in the `Keyword` match arm.
- **Comment lost**: `has_non_comment_text` guard stops `drain_before` when a keyword sits between the comment and target offset. Multi-word interiors need `skip_text_check: true`.
- **Pending dropped**: `flush_drain` with `leading != NIL` zeroes pending. If pending held a LINE from the clause template, that break is lost.

### 4. Fix and verify (GREEN)

```sh
cargo test -p syntaqlite --features fmt,sqlite --test fmt_comments TEST_NAME -- --nocapture
cargo test -p syntaqlite --features fmt,sqlite
cargo build -p syntaqlite-cli && tools/run-integration-tests
```

All 7 integration suites must pass (including ~650 idempotency checks).

Versions

The database has no other skills named debug-formatter.

Database snapshot: 13.11.2026 · package version d357746965b6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95sql-formatter
    This skill should be used when the user asks to format SQL code, polish SQL queries, improve SQL readability, or work with .sql files. Use when queries mention SQL formatting, code beautification, Oracle SQL, or database query polishing.
  • 100commit-message-formatter
    Manage commit message formatter operations. Auto-activating skill for DevOps Basics. Triggers on: commit message formatter, commit message formatter Part of the DevOps Basics skill category. Use when working with commit message formatter functionality. Trigger with phrases like…
  • 100debug-deep
    Deep debugging using multi-agent analysis and error pattern matching. Use when user reports a bug, error, crash, or unexpected behavior. Triggers on "debug", "fix", "broken", "crash", "error", "bug".
  • 100formatting
    Apply when writing or editing any file's whitespace or comments. Esposter's spacing and comment conventions — where blank lines go, and what a comment says and where it sits.
  • 90code-style-lint
    Discipline for code style and static analysis, adopt the ecosystem's established formatter as the non-negotiable source of truth, enforce it at pre-commit and CI rather than in review, and treat linting (real defects) as a separate concern from formatting (appearance). Use when…
  • 100visual-rhythm
    This skill should be used when the user's code has inconsistent whitespace, missing blank lines between logical sections, cramped or overly spaced code, or when the visual structure does not match the logical structure. Covers whitespace as punctuation and the rule that code is…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.