pipeline-auditor

name

pipeline-auditor

description

Audit/regression checks for the evidence-first survey pipeline: citation health, per-section coverage, placeholder leakage, and template repetition. **Trigger**: auditor, audit, regression test, quality report, 审计, 回归测试. **Use when**: `output/DRAFT.md` exists and you want a deterministic PASS/FAIL report before LaTeX/PDF. **Skip if**: you are still changing retrieval/outline/evidence packs heavily (audit later). **Network**: none. **Guardrail**: do not change content; only analyze and report.

Pipeline Auditor (draft audit + regression)

Purpose: a deterministic “regression test” for the writing stage.

It answers:

• did we leak placeholders or planner talk?
• did citation scope drift?
• did the draft fall back to generator voice (navigation/narration templates)?
• is citation density/health sufficient for a survey-like draft?

This skill is analysis-only. It does not edit content. For survey/deep, style/citation-shape violations are blocking by default.

Inputs

• output/DRAFT.md
• outline/outline.yml
• Optional (recommended):
  • outline/evidence_bindings.jsonl
  • citations/ref.bib

Outputs

• output/AUDIT_REPORT.md

What it checks (deterministic)

A150++ citation targets (used by the auditor):

• Per-H3: >=12 unique citations (deep: >=14).

• Global: >=150 unique citations across the full draft (recommended target: 165; deep floor: 165).

• Placeholder leakage: ellipsis (..., …), TODO markers, scaffold tags.

• Outline alignment: section/subsection order vs outline/outline.yml.

• Survey tables (survey deliverable): require >=2 Markdown tables in the merged draft (index tables live in outline/tables_index.md) (inserted by section-merger from outline/tables_appendix.md).

• Paper voice anti-patterns:

  • narration templates (This subsection ..., In this subsection ...)
  • slide navigation (Next, we move ..., We now turn to ...)
  • pipeline voice (this run, “pipeline/stage/workspace” in prose)

• Evidence-policy disclaimer spam: repeated “abstract-only/title-only/provisional” boilerplate inside H3 bodies.

• Meta survey-guidance phrasing: survey synthesis/comparisons should ....

• Synthesis stem repetition: repeated Taken together, ... and similar high-signal generator stems.

• Numeric claim context: numbers without minimal evaluation context tokens (benchmark/dataset/metric/budget/cost).

• Citation health (if citations/ref.bib exists): undefined keys, duplicates, basic formatting red flags.

• Citation-shape hard gate (survey/deep): no adjacent citation blocks ([@a] [@b]), no duplicate keys inside one block ([@a; @a]), and per-H3 mid-sentence citation ratio >=30%.

• Citation scope (if outline/evidence_bindings.jsonl exists): citations used per H3 should stay within the bound evidence set.

How to use the report (routing table)

Treat output/AUDIT_REPORT.md as a “what to fix next” router.

Common FAIL families -> responsible stage/skill:

• Placeholders / leaked scaffolds

  • Fix: C2–C4 artifacts are not clean. Route to subsection-briefs / evidence-draft / writer-context-pack, then rewrite affected sections.

• Missing overview tables (draft has <2 tables)

  • Fix: ensure table-schema + appendix-table-writer produced outline/tables_appendix.md (>=2 tables, citation-backed, no placeholders), then rerun section-merger (tables insert as an Appendix block by default).

• Planner talk in transitions / narrator bridges

  • Fix: rerun transition-weaver (and ensure briefs include bridge_terms / contrast_hook), then re-merge.

• Narration templates / slide navigation inside H3

  • Fix: rewrite the failing sections/S*.md via writer-selfloop (local, section-level) or subsection-polisher.

• Evidence-policy disclaimer spam

  • Fix: keep evidence policy once in Intro/Related Work (front matter), delete repeats in H3 (use draft-polisher or local section rewrites).

• Citation scope drift (out-of-scope bibkeys)

  • Fix: either (a) rewrite the subsection to stay in-scope, or (b) fix mapping/bindings (section-mapper → evidence-binder) and regenerate packs.

• Global unique citations too low

  • Fix: citation-diversifier → citation-injector (NO NEW FACTS), then draft-polisher.

• Intro/Related Work too thin / too few cites

  • Fix: rewrite the corresponding sections/S<sec_id>.md front-matter file via writer-selfloop (front-matter path) using dense positioning + method paragraph.

Prevention guidance (what upstream writers should do)

If you want the auditor to PASS without a heavy polish loop:

• Start each H3 with a content claim + thesis (avoid narration templates).
• Use explicit contrasts and at least one evaluation anchor paragraph.
• Embed citations per claim (avoid trailing cite dumps).
• Put evidence-policy limitations once in the front matter, not in every H3.

Script

Quick Start

• python .codex/skills/pipeline-auditor/scripts/run.py --help
• python .codex/skills/pipeline-auditor/scripts/run.py --workspace workspaces/<ws>

All Options

• --workspace <dir>
• --unit-id <U###> (optional; for logs)
• --inputs <semicolon-separated> (rare override; prefer defaults)
• --outputs <semicolon-separated> (rare override; default writes output/AUDIT_REPORT.md)
• --checkpoint <C#> (optional)

Examples

• Run audit after global-reviewer and before LaTeX/PDF:
  • python .codex/skills/pipeline-auditor/scripts/run.py --workspace workspaces/<ws>

Troubleshooting

Issue: audit fails due to undefined citations

Fix:

• Regenerate citations with citation-verifier and ensure citations/ref.bib contains every cited key.

Issue: audit fails due to narration-style navigation phrases

Fix:

• Rewrite as argument bridges (content-bearing handoffs, no navigation commentary) in the failing sections/* files, then re-merge.

Issue: audit fails due to "unique citations too low"

Fix:

• Run citation-diversifier to produce output/CITATION_BUDGET_REPORT.md.
• Apply it via citation-injector (edits output/DRAFT.md, writes output/CITATION_INJECTION_REPORT.md).
• Then run draft-polisher → global-reviewer → auditor.