AgentSkillsCN

appendix-table-writer

为附录精心策划面向读者的调研表格（布局简洁、信息密度高），仅选用符合范围的证据与现有的引用键。 **触发条件**：附录表格、可发表表格、调研表格、读者表格、附录表格、可发表表格、综述表格。 **适用场景**：当你已拥有 C4 类成果（证据包 + 锚点表 + 引用文献），并希望生成的表格看起来更像一份真实的调研报告（而非内部日志）时。 **跳过条件**：若 `outline/tables_appendix.md` 文件已存在且经过优化（至少包含 2 张表格；引用依据充分；不含占位符；不以索引为导向），则无需再次更新。 **网络要求**：无需联网。 **防护措施**：禁止杜撰事实；避免使用行业术语；不得出现段落式单元格；仅使用 `citations/ref.bib` 中已有的引用键。

SKILL.md
--- frontmatter
name: appendix-table-writer
description: |
  Curate reader-facing survey tables for the Appendix (clean layout + high information density), using only in-scope evidence and existing citation keys.
  **Trigger**: appendix tables, publishable tables, survey tables, reader tables, 附录表格, 可发表表格, 综述表格.
  **Use when**: you have C4 artifacts (evidence packs + anchor sheet + citations) and want tables that look like a real survey (not internal logs).
  **Skip if**: `outline/tables_appendix.md` already exists and is refined (>=2 tables; citation-backed; no placeholders; not index-y).
  **Network**: none.
  **Guardrail**: no invented facts; no pipeline jargon; no paragraph cells; use only keys present in `citations/ref.bib`.

Appendix Table Writer (publishable survey tables)

Why this exists

The pipeline can produce index tables that are useful for planning/debugging, but read like internal artifacts.

This skill writes publishable, reader-facing tables that can live in an Appendix:

  • •cleaner layout
  • •higher information density
  • •survey-style organization (methods/benchmarks/risks), not intermediate state

Index tables remain in outline/tables_index.md and should not be copied verbatim into the paper.

Inputs

  • •outline/table_schema.md (table intent + evidence mapping)
  • •outline/tables_index.md (internal index; optional but recommended)
  • •outline/subsection_briefs.jsonl
  • •outline/evidence_drafts.jsonl
  • •outline/anchor_sheet.jsonl
  • •citations/ref.bib
  • •Optional: GOAL.md

Output

  • •outline/tables_appendix.md

Roles (use explicitly)

Survey Table Curator (reader lens)

Mission: choose tables a reader actually wants in a survey Appendix.

Do:

  • •prefer 2-3 tables that answer big questions (methods, evaluation, risks)
  • •make rows comparable (same row unit across the table)
  • •make the table legible without reading the whole paper

Avoid:

  • •one-row-per-H3 index dumps
  • •columns named like internal axes ("axes", "blocking_missing", "evidence readiness")

Production Editor (layout)

Mission: make the table look publishable in LaTeX.

Do:

  • •keep columns <= 4
  • •keep cells short (phrases, not sentences)
  • •use <br> sparingly (0-1 per cell; never a list dump)

Avoid:

  • •6-8 columns with tiny unreadable text
  • •cells that look like notes (semicolon chains + slash lists + long parentheticals)
  • •slash-separated axis markers (A/B/C) in captions/headers/cells (post-merge voice gate will flag them); use commas or 'and' instead
  • •internal axis jargon that reads like an intermediate artifact once printed (e.g., calling table columns "tokens"); prefer "protocol details/metadata/assumptions"

Evidence Steward (verifiability)

Mission: prevent hallucinations.

Do:

  • •every row must include citations in a dedicated column (e.g., "Key refs")
  • •only restate what appears in evidence packs / anchor sheet
  • •when evidence is thin, prefer fewer rows with stronger grounding

Avoid:

  • •"representative works" with no supporting claim in packs/anchors
  • •adding benchmark/method details not present upstream

Table contract (publishable, Appendix-ready)

outline/tables_appendix.md must:

  • •contain >=2 Markdown tables
  • •use a caption line before each table, e.g. **Appendix Table A1. ...**
  • •contain no headings (#, ##, ###) inside the file (the merger adds an Appendix heading)
  • •contain no placeholders (TODO, TBD, FIXME, ..., unicode ellipsis)
  • •contain citations in rows using [@BibKey] (keys must exist in citations/ref.bib)
  • •avoid pipeline jargon and index-like column names

Workflow (explicit inputs)

  • •Start from GOAL.md (scope) and outline/table_schema.md (what each table must answer).
  • •Use outline/tables_index.md as a shortlist source, but do not paste it verbatim.
  • •Fill rows/cells using outline/subsection_briefs.jsonl, outline/evidence_drafts.jsonl, and outline/anchor_sheet.jsonl (no guessing).
  • •Validate every cited key against citations/ref.bib.

Recommended Appendix tables (default set)

If you are unsure what to build, start with these two:

  1. •Method/architecture map (representative works)
  • •Row unit: work/system line (not H3 id)
  • •Columns (example):
    • •Work (short name)
    • •Core idea (1 short phrase)
    • •Loop + interface assumptions (1 short phrase; reader-facing)
    • •Key refs (2-4 cite keys)
  1. •Evaluation protocol / benchmark map
  • •Row unit: benchmark / evaluation setting (or a canonical protocol dimension if benchmarks are thin)
  • •Columns (example):
    • •Benchmark / setting
    • •Task + metric (phrases, not definitions)
    • •Key protocol constraints (budget/cost/latency/steps/tool access/threat model)
    • •Key refs (2-4 cite keys)

Optional third (only if it stays clean): 3) Risk / threat-surface map

  • •Row unit: threat/failure mode category
  • •Columns: surface; why it matters; mitigation pattern; key refs

Positive / negative examples (style)

Bad (index table / internal notes):

  • •Column: "Axes"
  • •Cell: planning / memory / tools / eval / safety (slash dump)
  • •Rows: every H3 id with 5+ <br> lines

Good (survey table):

  • •Column labels are reader-facing ("Core idea", "Task + metric", "Constraint")
  • •Cells are short phrases (no narration)
  • •A reader can scan and compare rows quickly

Also good (avoid intermediate-artifact tells):

  • •Don't label columns as "token(s)". If you need the idea, rewrite as "protocol details/metadata/assumptions".
  • •Avoid ASCII arrows like -> inside cells; prefer natural phrasing (e.g., "interleaves reasoning traces with tool actions").

When to stop / route upstream

If you cannot fill a row without guessing:

  • •remove the row (prefer fewer, solid rows), and
  • •route upstream: strengthen evidence-draft / anchor-sheet for that area.

Script (validator-only)

Quick Start

  • •python .codex/skills/appendix-table-writer/scripts/run.py --help
  • •python .codex/skills/appendix-table-writer/scripts/run.py --workspace workspaces/<ws>

All Options

  • •--workspace <workspace_dir> (required)
  • •--unit-id <id> (optional; used only for runner bookkeeping)
  • •--inputs <a;b;c> (optional; ignored by the validator; kept for runner compatibility)
  • •--outputs <relpath> (optional; defaults to outline/tables_appendix.md)
  • •--checkpoint <C#> (optional; ignored by the validator)

Examples

  • •

    Validate the default appendix tables file:

    python .codex/skills/appendix-table-writer/scripts/run.py --workspace workspaces/e2e-agent-survey-latex-verify-YYYYMMDD-HHMMSS

  • •

    Validate a workspace that writes appendix tables to a non-standard path:

    python .codex/skills/appendix-table-writer/scripts/run.py --workspace workspaces/<ws> --outputs outline/tables_appendix.md

Notes:

  • •This script does not write table content. It only validates that outline/tables_appendix.md is Appendix-ready.
  • •It always writes a short report to output/TABLES_APPENDIX_REPORT.md.