Linter Investigation

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-fixes fixes 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...
  EOF

  Match the reader to the flavor (-f gfm, -f commonmark, -f markdown for Pandoc). For a .qmd, quarto is the higher-level oracle.

• panache's own view — panache parse <file> (with --to for projection, --flavor to 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 to smoke-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

1. 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/r4ds or rstudio/bookdown for R Markdown; quarto-dev/quarto-web for Quarto) and confirm before cloning.

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

3. Lint the tree, capture everything. Capture both streams (per-violation diagnostics may print to stdout, errors to stderr; lint exits non-zero on violations):

   target/release/panache lint "$SCRATCH/<name>" >lint.out 2>lint.err

   panache lints .qmd/.md/.Rmd/.Rmarkdown. Set --flavor if the repo's files need a specific dialect and extension inference isn't enough.

4. 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 -rn

5. Triage (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 CST

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

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

7. Fan out for volume (recommended). For a big finding set, spawn parallel triage subagents—one per rule-bucket—each given the absolute target/release/panache path, the lint.out/lint.err paths, 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.

8. 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-rule and the golden-case conventions under tests/fixtures/cases/ and crates/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 accept after reviewing new snapshots.

   Record everything you don't fix as follow-ups in TODO.md in the house style, each with a minimal reproducer, the flavor, and the pandoc/quarto behavior. Commit only if the user asks—atomic, Conventional Commits.

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