linter-investigation
Skill247 starsChanged 25 days agoMITView on GitHub
Investigate panache's linter (and, secondarily, its parser) against a
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- add-lint-ruleSkill
- add-syntax-constructSkill
- commonmark-conformanceSkill
- external-toolsSkill
- html-conformanceSkill
- math-parser-formatterSkill
- pandoc-ir-migrateSkill
- perf-investigationSkill
- smoke-test-triageSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 132
Add a failing golden/fixture case first and watch it fail, following panache's add-lint-rule and the golden-case conventions under …
- Very specific: line 137
Run the gates: cargo test, cargo clippy --all-targets --all-features -- -D warnings, cargo fmt -- --check.
- Distinctive: line 143
Commit only if the user asks—atomic, Conventional Commits.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.
Files
Point panache's linter at a large body of real Quarto/Markdown and hunt for linter quality bugs: false positives, incorrect spans, and unsafe fixes. This is the primary goal. Parse problems are a secondary catch—Markdown is permissive, so parser bugs rarely surface as hard errors; they show up as a construct panache parses differently from pandoc, or as a mis-parse that makes a lint rule misfire. Report those, but keep the center of gravity on the linter, not a full parser/AST audit.
This is distinct from the smoke-test-triage skill. That one reacts to the
weekly automated corpus scan's formatter regressions (losslessness,
idempotence, format-error, panic) filed as GitHub issues. This skill is
proactive and interactive: you choose a repo and go looking for linter/parser
quality problems. Formatter losslessness and idempotence are out of scope
here—leave them to smoke-test-triage.
The core principle (read first)
A finding is only a bug once pandoc/quarto shows panache is wrong. Real
corpora mix flavors (Pandoc, Quarto, R Markdown, GFM, CommonMark, MyST), and a
construct's meaning depends on the active flavor—so always triage with the right
--flavor. Classify each suspicious finding into exactly one of:
- True positive — panache is right; move on.
- False positive — panache flags legitimate Markdown. The highest-value find.
- Incorrect span — the finding is real but the highlighted range is wrong.
- Unsafe fix — an autofix that changes the rendered document (Markdown is
full of significant whitespace, list indentation, and inline-boundary rules),
breaks the source, or mangles a fenced code block / YAML block. Test it;
--unsafe-fixesfixes especially warrant scrutiny. - Parser bug — valid Markdown that panache parses differently from pandoc in a way that matters (wrong block/inline structure). Confirm against the pandoc AST.
The oracle (pandoc and quarto are installed)
pandoc AST — the ground truth for how a construct parses. Compare structure with the native/JSON AST:
pandoc -f markdown -t native <<'EOF' ...snippet... EOFMatch the reader to the flavor (
-f gfm,-f commonmark,-f markdownfor Pandoc). For a.qmd,quartois the higher-level oracle.- panache's own view —
panache parse <file>(with--tofor projection,--flavorto pin the dialect) prints the CST;panache debug format --checks all --dump-dir <dir> <file>dumps input/parse/format artifacts (this is the losslessness/idempotence diagnostic path—use it to understand a mis-parse, even though fixing those regressions belongs tosmoke-test-triage).
A linter false positive is usually a Markdown-semantics judgment settled from
the pandoc AST plus panache's parse tree; reach for quarto when the question is
Quarto-specific (shortcodes, div syntax, execution blocks).
Workflow
- Target. Take the repo from the user's argument (GitHub
owner/name, clone URL, or local path). If none is given, propose a good default (hadley/r4dsorrstudio/bookdownfor R Markdown;quarto-dev/quarto-webfor Quarto) and confirm before cloning. Setup (parallel/background). Build the release binary and shallow-clone into the session scratchpad directory (not bare
/tmp), at once:cargo build --release git clone --depth 1 https://github.com/<owner>/<name>.git "$SCRATCH/<name>"panache is a workspace; the parser lives in
crates/panache-parser.Lint the tree, capture everything. Capture both streams (per-violation diagnostics may print to stdout, errors to stderr;
lintexits non-zero on violations):target/release/panache lint "$SCRATCH/<name>" >lint.out 2>lint.errpanache lints
.qmd/.md/.Rmd/.Rmarkdown. Set--flavorif the repo's files need a specific dialect and extension inference isn't enough.Summarize by rule. Count findings per rule to prioritize the high-volume and high-risk buckets:
grep -oE '(warning|error): [a-z-]+' lint.err lint.out | sort | uniq -c | sort -rnTriage (the heart of the work). For each priority rule, pull real findings, open the cited source line, and reduce each suspect to a minimal reproducer piped to the tool:
printf '...\n' | target/release/panache lint --flavor <flavor> printf '...\n' | target/release/panache parse --flavor <flavor> # inspect CSTFor a suspected mis-parse, isolate the trigger by bisecting context (block vs inline, inside a list/blockquote/fenced block, which flavor), varying one axis at a time until the minimal shape is pinned—then diff panache's structure against pandoc's AST for the same snippet and flavor.
- Verify against the oracle. Promote a suspicion to a bug only after pandoc/quarto agrees the construct means what you claim—under the flavor the file actually uses.
- Fan out for volume (recommended). For a big finding set, spawn parallel
triage subagents—one per rule-bucket—each given the absolute
target/release/panachepath, thelint.out/lint.errpaths, the classification scheme (with the flavor caveat), and the pandoc/quarto oracle recipe. Each returns minimal reproducers, per-category verdicts, and an FP-rate assessment. Fix or record. For the cleanest, well-isolated bugs, fix TDD-style, honoring panache's tenets (parser bugs fixed in the parser; losslessness sacred; a fix must not change rendered meaning):
- Add a failing golden/fixture case first and watch it fail, following
panache's
add-lint-ruleand the golden-case conventions undertests/fixtures/cases/andcrates/panache-parser/tests/(reduce from the corpus). - Fix at the root cause; re-verify against pandoc/quarto.
- Run the gates:
cargo test,cargo clippy --all-targets --all-features -- -D warnings,cargo fmt -- --check;cargo insta acceptafter reviewing new snapshots.
Record everything you don't fix as follow-ups in
TODO.mdin the house style, each with a minimal reproducer, the flavor, and the pandoc/quarto behavior. Commit only if the user asks—atomic, Conventional Commits.- Add a failing golden/fixture case first and watch it fail, following
panache's
- Report back. State plainly: bugs found (fixed vs. documented) with copy-pasteable reproducers (and the flavor each assumes); false-positive categories per rule; incorrect-span issues; which rules you verified clean; and follow-ups recorded. Be faithful about which flavor each verdict was checked under.
panache-specific notes
- Flavor is load-bearing. The same text is valid-but-different across Pandoc,
Quarto, GFM, CommonMark, and MyST. Never triage without pinning
--flavor, and always report which flavor a finding assumes—an "FP" under GFM may be correct under Pandoc. - YAML front matter and fenced code blocks are hotspots. Rules and fixes that
touch a
---metadata block or a code fence can corrupt structured content; test any such fix by re-parsing and by round-tripping through pandoc. - Unsafe fixes change rendered meaning. Significant whitespace, list-item
indentation, and inline emphasis boundaries make "cosmetic" edits risky.
--unsafe-fixesedits deserve the most scrutiny. - Workspace layout: the parser is
crates/panache-parser;debug format --checks all --dump-diris the artifact-dump path for understanding a mis-parse (fixing losslessness/idempotence itself issmoke-test-triage's job).
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
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.

