paper-facing-docs

name	paper-facing-docs
description	Draft or review benchmark and manuscript-support docs conservatively, with explicit provenance, reproducibility, and caveat handling.
category	benchmark-evidence
kind	atomic
phase	context
requires_write	false
requires_slurm	false
requires_benchmark_artifacts	true
delegates_to	[]
output_schema	skill_run_summary.v1

Paper-Facing Docs

When to use

Use this skill for any documentation that can affect benchmark interpretation, manuscript claims, or public-facing provenance statements.

Read First

• docs/code_review.md
• docs/benchmark_camera_ready.md
• docs/benchmark_artifact_publication.md
• relevant issue execution notes under docs/context/
• docs/benchmark_spec.md

Workflow

1. Validate the claim surface against existing benchmark definitions.
2. Check reproducibility breadcrumbs (config, command, seed policy, artifact path).
3. Mark caveats with plain-language risk language.
4. Review wording for unsupported causality or overclaim.
5. Add explicit provenance pointers before handoff.
6. For mixed or limited evidence, make the opening order: claim boundary, evidence status, major caveats and exclusions, uncertainty, then result interpretation.
7. State evidence status in one of: diagnostic-only, smoke evidence, nominal benchmark evidence, or paper-grade.

Proof and Guardrails

• Preserve fail-closed semantics: do not present fallback/degraded runs as success.
• For mixed, limited, or degraded evidence, require caveat-first ordering before any ranking/success language.
• Any claim must point to concrete reproducible artifacts.
• Use claim-boundary language early when confidence is below high confidence (approx 95%) and include numeric uncertainty.
• Prefer tracked canonical documents and execution notes for evidence.
• Use consistent evidence-tier wording: diagnostic-only, smoke evidence, nominal benchmark evidence, and paper-grade.
• Put fallback/degraded rows in caveats or exclusions before any ranking or success language.
• Place sub-95% confidence estimates, caveats, or conditions near the claim boundary, not after the conclusion.

Output

Paper-facing docs should:

• cite canonical benchmark/config surfaces,
• avoid overstating planner support,
• name remaining caveats in plain language,
• put claim boundaries before interpretation when evidence is mixed or limited.

Guardrails

• Stay within the skill scope declared in .agents/skills/skills.yaml.
• Prefer repository scripts and canonical docs before ad-hoc commands.
• Record blockers and validation gaps instead of overstating completion.