agentleFS
jolarsjolars/panache/.agents/skills/linter-investigation/SKILL.md

linter-investigation

Skill247 starsChanged 25 days agoMITView on GitHub

Investigate panache's linter (and, secondarily, its parser) against a

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
  1. Very specific:

    Add a failing golden/fixture case first and watch it fail, following panache's add-lint-rule and the golden-case conventions under …

    line 132
  2. Very specific:

    Run the gates: cargo test, cargo clippy --all-targets --all-features -- -D warnings, cargo fmt -- --check.

    line 137
  3. Distinctive:

    Commit only if the user asks—atomic, Conventional Commits.

    line 143

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

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-fixes edits deserve the most scrutiny.
  • Workspace layout: the parser is crates/panache-parser; debug format --checks all --dump-dir is the artifact-dump path for understanding a mis-parse (fixing losslessness/idempotence itself is smoke-test-triage's job).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.