template-pipeline-debugging
Systematic pipeline DAG failure triage for the Research Project Template. USE WHEN ./run.sh or execute_pipeline.py fails, a stage stalls (setup, tests, analysis, render, validate, LLM, copy), pytest/coverage gate fails mid-pipeline, PDF render or validate breaks, Project Analysis finishes too fast with no figures, or user says pipeline debug, stage failed, resume checkpoint, core-only triage — even without naming this skill or docs/prompts.
Best use case
template-pipeline-debugging is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Systematic pipeline DAG failure triage for the Research Project Template. USE WHEN ./run.sh or execute_pipeline.py fails, a stage stalls (setup, tests, analysis, render, validate, LLM, copy), pytest/coverage gate fails mid-pipeline, PDF render or validate breaks, Project Analysis finishes too fast with no figures, or user says pipeline debug, stage failed, resume checkpoint, core-only triage — even without naming this skill or docs/prompts.
Teams using template-pipeline-debugging should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/pipeline-debugging/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How template-pipeline-debugging Compares
| Feature / Agent | template-pipeline-debugging | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Systematic pipeline DAG failure triage for the Research Project Template. USE WHEN ./run.sh or execute_pipeline.py fails, a stage stalls (setup, tests, analysis, render, validate, LLM, copy), pytest/coverage gate fails mid-pipeline, PDF render or validate breaks, Project Analysis finishes too fast with no figures, or user says pipeline debug, stage failed, resume checkpoint, core-only triage — even without naming this skill or docs/prompts.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Pipeline debugging ## Natural invoke - "My pipeline failed at PDF render for template_code_project" - "Project Analysis finishes in under a second with no figures — help debug" - "run.sh --pipeline failed; what's the first real error?" - "Resume from checkpoint after fixing project tests" ## Inputs to confirm - **Project** — from [`docs/_generated/active_projects.md`](../../_generated/active_projects.md); infer from context if obvious. - **Invocation** — full vs `--core-only`, `--resume`, `--skip-infra`, multi-project. - **Failing stage** — if unknown, reproduce first. ## Workflow 1. **Reproduce** — re-run the failing invocation verbatim; capture full stderr/stdout and exit status. Quote the **first** real error, not the last line. Name the failing stage (setup, infra tests, project tests, analysis, render, validate, LLM review, LLM translations, copy). 2. **Isolate** — run that stage's underlying command directly (pytest target, analysis script, validation CLI, renderer). Use `--resume` to skip good upstream stages while iterating. 3. **Classify** — dependency/uv gap, missing system tool (LaTeX/pandoc-crossref), nondeterministic input, coverage gate, undefined citation/cross-ref, thin-orchestrator violation (logic in `scripts/` not `src/`), or logic bug. When **Project Analysis** completes in under a second with no figures, treat as import/dependency failure and isolate via `scripts/02_run_analysis.py`. Trace where bad state **enters**; fix at ingestion. 4. **Fix minimally** — re-run full pipeline green; confirm `--resume` shows no upstream regression. Update `projects/<n>/AGENTS.md` / `README.md` if the failure mode was non-obvious. ## Deliverables - Failing stage, first real error (quoted), root cause, minimal patch (file + snippet). - Exact commands + raw exit status proving green. - Do not claim "fixed" without a clean full-pipeline run. ## Verification commands ```bash uv sync uv run python scripts/execute_pipeline.py --project <project> uv run python scripts/execute_pipeline.py --project <project> --resume uv run python scripts/execute_pipeline.py --project <project> --core-only uv run python scripts/01_run_tests.py --project <project> uv run pytest projects/<project>/tests/ --cov=projects/<project>/src --cov-fail-under=90 -q uv run python -m infrastructure.validation.cli prerender projects/<project>/manuscript --repo-root . uv run python -m infrastructure.validation.cli pdf output/<project>/pdf/ uv run python -m infrastructure.rendering.latex_package_validator LOG_LEVEL=0 uv run python scripts/execute_pipeline.py --project <project> --resume ``` Stage semantics: [`docs/RUN_GUIDE.md`](../../RUN_GUIDE.md), [`AGENTS.md`](../../../AGENTS.md). ## When NOT to use - **Determinism / double-run drift only** → [reproducibility-audit](../reproducibility-audit/SKILL.md) - **Claim truth in prose** → [manuscript-claim-verification](../manuscript-claim-verification/SKILL.md) - **Validation infrastructure deep dive without a failing stage** → [validation-quality](../validation-quality/SKILL.md)
Related Skills
template-validation-quality
Run validation CLI, prerender, markdown/PDF/integrity gates, and QA workflows for the Research Project Template. USE WHEN validate manuscript, check PDF for ?? refs, prerender gate, link checker, output integrity, or pre-commit validation — even without validation_quality prompt.
template-test-creation
Create pytest suites under the no-mocks policy — real data, temp files, subprocess, pytest-httpserver. USE WHEN adding tests, raising coverage, testing new src/ module, or user forbids mocks.
template-reproducibility-audit
Deterministic reproducibility audit — fixed seeds, regenerate-from-clean, double-run diff before Zenodo/arXiv/release. USE WHEN outputs drift between runs, "worked on my machine", need regenerate-from-clean proof, or pre-release reproducibility check — even without naming docs/prompts.
template-refactoring
Clean-break refactors with migration for the Research Project Template — move logic to src/, split modules, rename APIs with test updates. USE WHEN restructuring code, extracting modules, removing duplication, or migration without behavior change.
template-methods-orchestration
Repo-wide methods orchestration workflow for the Research Project Template. USE WHEN the user asks to add, audit, improve, or validate methods, methodology, method contracts, stage-to-method wiring, artifact/evidence provenance, or orchestration across template projects.
template-manuscript-cross-references
Audit or author registry-driven manuscript cross-refs — labels.yaml, [[FIG:]], [[THMREF:]], [[VAR:]] tokens. USE WHEN fixing figure/equation/theorem numbering, orphan registry keys, hard-coded "Theorem 7.3" in prose, or [[MISSING:]] injection failures — even for Pandoc projects that also use a YAML registry.
template-manuscript-creation
Scaffold a research manuscript and project layout from a research brief — sections, config.yaml, src/, scripts/, tests. USE WHEN starting a new paper, new projects/ tree, manuscript from topic description, or aligning with template_code_project exemplar — even without copy-paste prompts.
template-manuscript-claim-verification
Triple-pass verification of every manuscript claim against code, data, refs, and renderer; repair prose while staying renderable. USE WHEN pre-submission, pre-Zenodo, pre-arXiv, abstract numbers disagree with CSV, citations do not support sentences, or user asks to triple-check / verify every claim — even without docs/prompts. Not for casual PDF summary.
template-feature-addition
End-to-end feature work across src/, scripts/, tests/, manuscript, and docs for the Research Project Template. USE WHEN adding a pipeline-visible feature, new analysis stage, manuscript-facing output, or cross-layer integration — even without feature_addition prompt.
template-documentation-creation
Author or refresh AGENTS.md and README.md for template directories — accurate commands, Mermaid where helpful, link _generated/active_projects.md. USE WHEN folder needs AGENTS, README audit, doc contract fix, or signposting after code change — even without documentation_creation prompt.
template-deep-research
Template-native research intake, literature search, source verification, synthesis, fact-checking, and systematic-review planning. USE WHEN the user asks to research a topic, build a literature corpus, fact-check claims, prepare a PRISMA-style review, or clarify a research question before manuscript work.
template-comprehensive-assessment
Full checkout audit for the Research Project Template — tests, architecture, docs, manuscript, pipeline. USE WHEN user asks for comprehensive assessment, full repo review, health check across projects, audit everything, or pre-merge sanity sweep for template exemplars — even without naming docs/prompts or a skill. Not for single failing stage only.