跳到正文
𝕏 Garry Tan(x.com)·· 6 天前精選品質評分68
重點導讀

同事收到 PDF 或 Markdown 報告後,常難以知道數字怎麼算出來,也不容易重做結果。

  • Garry Tan 分享一套附錄寫法,要求有資料查詢或數字的報告,在文末說清楚資料來源、查詢內容、計算方式、重建檔案的指令,以及資料可能變動的地方。
  • 這樣同事就能用自己的 AI 助理照著步驟重做,檢查結果和假設是否一致。

AI 伴隨問答

自備 Key 深度分析

針對這篇報導有疑問?可直接點選快捷問題或向 AI 追問背景脈絡與技術細節:

推薦理由

這套附錄方法把資料分析的查詢、計算假設與重建步驟留在報告末尾,讓同事能用自己的 AI 助理重做結果並看出差異。

Garry Tan
Garry Tan@garrytan
·6 天前
𝕏

I send around PDFs and markdown files to my coworkers so much and they use their agents to make sense of the world too, so I started using this skill methodology-appendix to make sure their agents could replicate what my agents found.

---
name: methodology-appendix
description: "Every data-backed report or memo ends with a Methodology / Replication Appendix: the signal choice and its sensitivity, verbatim queries, derivation pseudocode over named constants, the rebuild command, and drift/limits. Appended by default, without asking."
---

# Methodology / Replication Appendix

## Rule

Any report, PDF or page whose conclusions rest on data queries ends with a
**Replication Appendix**. It is a working recipe, not a citation list. The test:

> A reader with an agent and equivalent data access can regenerate the document
> end to end from the appendix alone, without contacting the author.

If a reader would have to ask "which column did you use?", "what date was this
pulled?" or "how do I rebuild the PDF?", the appendix failed.

## Body voice

The body states conclusions plainly. No process narration ("I was asked...",
"on the first pass..."), no self-grading. The first sentence after the title
contains a finding. Everything about how you got there goes in the appendix at
the end, written for forensic recreation.

## When this fires

Always, automatically, for:
- analysis memos backed by database or API queries
- any PDF sent to partners, executives or external stakeholders
- pages presenting quantitative findings
- anything with tables of counts, rates or percentiles

Skip for narrative or qualitative writing, meeting notes, personal memos,
short ephemera, and documents with no data spine. Do not ask permission.

## The six sections

### 1. Header

```markdown
## Replication Appendix

A reader with an agent and equivalent data access can regenerate every number
and rebuild this document from this appendix alone.

**Access required:** <tool/CLI + auth, internal APIs>
**Snapshot date:** <ISO date>. Live-data documents won't reproduce exactly after this date; see Drift.
```

### 2. Signal definitions and the choice that mattered

The most important section. Analyses usually turn on one column or threshold
choice. Name it, name the alternatives, state the impact.

```markdown
### Signal definitions

| Field | What it is | Why chosen / rejected |
|---|---|---|
| `score_a` | Ensembled score | **Primary.** More predictive per <source>. |
| `score_b` | Single-model score | Rejected as primary; kept for contrast. |
| final_decision | Human decision object | Not queried. Known gap. |

**Outcome sensitivity:** switching from score_b to score_a moved the headline
count from N1 to N2 and changed claim X. A replication that changes the signal
column will not match these numbers.
```

Always include an **Outcome sensitivity** line. If a different defensible choice
changes the conclusion, the reader must know before quoting it.

### 3. Verbatim queries

Every query that produced a number, copy-pasteable, in document order, labelled
by the finding it supports. Never paraphrase SQL. Never write "similar to the
above." Add schema notes a replicator would otherwise get wrong: enum meanings,
non-obvious joins, columns that seem to exist but don't.

### 4. Derivation pseudocode

Queries give raw counts; the document has derived figures. Show the arithmetic,
with assumptions as named constants a reader can swap.

```
ITEMS_PER_DAY = 8 # observed median, <period>
YIELD_HAIRCUT = 0.10..0.15 # marginal cases convert below observed rate

gap = count(status = REJECTED and score >= threshold)
extra_days = gap / ITEMS_PER_DAY
added_wins = gap * YIELD_HAIRCUT
```

Different constants change the recommendation, not just the number, so they
must be visible.

### 5. Rebuild command

Exact commands from source markdown to verified PDF, plus a visual check
(e.g. `pdfinfo` page count, `pdftoppm` a couple of pages and look at them).
Name the source of record: the PDF is a render, never the original.

### 6. Drift, limits and known gaps

- **Live data moves.** What was mid-flight at snapshot; what is closed and stable.
- **Coverage gaps.** Fields only populated for part of the range, and how tables were restricted rather than shown with misleading denominators.
- **What this cannot see.** Inputs to the real decision that the data lacks.
- **Retractions.** Any claim withdrawn between versions, and why.

## Procedure

1. Log queries verbatim as you run them. Reconstructed SQL is how appendices go wrong.
2. Write the analysis.
3. Append the six sections before rendering.
4. Name the signal choice and its outcome sensitivity.
5. Render, check visually, then send.
6. On revision, update the appendix in the same commit as the finding. An appendix describing a superseded method is worse than none.

## Quality bar

- [ ] Could a reader re-run this without asking me anything?
- [ ] Is every headline number traceable to a pasted query?
- [ ] Is the signal/threshold choice named, with alternatives and impact?
- [ ] Are derived figures arithmetic over named constants?
- [ ] Is the rebuild command present and correct?
- [ ] Are drift, coverage gaps and retractions stated?

## Anti-patterns

- **Citation theater:** table names instead of runnable queries.
- **Reconstructed SQL:** retyped from memory, drifted from what ran.
- **Silent signal choice:** one column presented as "the score" when a defensible alternative changes the answer.
- **Buried assumptions:** constants hard-coded in prose.
- **Stale appendix:** findings revised, appendix untouched.
- **Asking first:** this is a default, not an offer.

推文來源 · X (Twitter)在 X 參與討論
來源: Garry Tan (x.com)
在 X 查看推文

讀者討論

理性交流 · 即時討論