---
name: formal-delivery-package
description: Use when packaging research or analysis outputs into a formal deliverable folder or ZIP for a supervisor, collaborator, client, sequencing company, or other external recipient, especially when the package needs neutral formal wording, requester/provider labels, bundled analysis_code and analysis_data folders, existing HTML or README updates, and a final audit for missing files, internal-only phrases, and leaked absolute paths.
---

# Formal Delivery Package

## Overview

Assemble a formal delivery package from results that already exist. Treat this as packaging, wording control, and boundary preservation — not as permission to rerun analyses unnecessarily or upgrade claims.

Prefer the smallest change that produces a complete, sendable package:
- If only one figure or one HTML changes, patch that file, sync the package, and rebuild the ZIP.
- If the tone, page structure, or bundled materials change materially, create or refresh a dedicated package directory.

## Non-Negotiable Rules

1. **Freeze the scientific boundary first.** Preserve the agreed claim boundary verbatim. If the project distinguishes internal validation from external validation, keep that distinction explicit in README and key pages.
2. **Package existing outputs before rerunning analysis.** Only rerun when the required source result does not exist or is demonstrably wrong.
3. **Use formal neutral wording.** Remove internal workflow language, personal chat language, escalation notes, path leaks, and any recipient-facing wording that exposes acquisition / cleaning / OCR / desensitization / editing process. For Chinese formal packages, do not name sections from a session / forwarding / internal-communication point of view; prefer neutral labels such as `分析小结`, `分析小结（正式记录）`, `正式查看`, `结果复核`, and `独立结果留档`.
4. **Include reproducibility materials.** A formal package should normally include both `analysis_code/` and `analysis_data/` or a clear manifest explaining any restriction.
5. **Rebuild and verify the ZIP after every package change.** Folder updated but ZIP stale is a failed delivery.

## Core Workflow

### 1. Lock the scope
Identify:
- target recipient and tone
- requester / demand side label
- analysis provider label
- exact scientific boundary that cannot drift
- whether this is a patch to an existing package or a new package directory

### 2. Choose the minimal packaging path
- **Patch existing package** when only local edits are needed in pages, figures, README, or attached tables.
- **Create or refresh a dedicated package** when the package needs a new structure, new naming, or different bundled materials.

### 3. Build the package skeleton
At minimum, formal packages should usually contain:
- `index.html`
- one or more report / note HTML files
- `README.md`
- `analysis_code/`
- `analysis_data/`
- `assets/` when figures are referenced by HTML
- key CSV / tables directly cited by the report

Read `references/package-checklist.md` for the detailed inclusion checklist.

### 4. Standardize wording and labels
Every package should make it easy for the recipient to identify:
- what this package is
- who requested it
- who prepared the analysis
- what to read first
- what code and data are bundled
- what claim boundary must not be overstated

Read `references/tone-and-structure.md` before editing README, cover pages, titles, or section headings. For Chinese-first deliverables, also read `references/chinese-workflow-templates.md` for ready-to-adapt templates.

For Chinese-first formal packages, standardize titles and navigation labels with explicit before/after checks:
- Prefer result-record wording over chat/session wording: `本次会话报告` → `分析小结`
- Prefer formal archive wording over forwarding wording: `可直接发送摘要` → `分析小结（正式记录）`
- Prefer neutral recipient actions on index cards / buttons / navigation: `直接转发` / `内部沟通` → `正式查看` / `结果复核` / `独立结果留档`
- If a heading sounds like a WeChat message, internal handoff, or "send this onward" instruction, rewrite it as a record, overview, note, or review page before shipping.

### 5. Bundle reproducibility files
For `analysis_code/`, include the smallest complete set of files that directly produced the included outputs, typically:
- main entrypoint
- active config file
- stage-specific pipeline scripts
- figure generation scripts
- any helper script required to reproduce included tables or figures

For `analysis_data/`, include the smallest approved set of input files that directly support the included outputs, typically:
- cleaned clinical or metadata tables
- omics / assay matrices used by the report
- grouping or label files
- mapping files used in split definitions or protocol explanation
- a README or manifest if data cannot be fully redistributed

If copied code or config files contain local machine paths, sanitize the packaged copy or replace those paths with recipient-safe placeholders before shipping.

### 6. Rebuild the ZIP
Use a deterministic recursive ZIP command from the parent directory of the package:

```bash
zip -rqX <package-name>.zip <package-dir-name>
```

Then confirm the archive contains the expected package root and key files:

```bash
unzip -l <package-name>.zip | sed -n '1,120p'
```

### 7. Audit before claiming completion
Run the bundled audit script. At minimum, check:
- required files exist
- requester / provider labels are present
- forbidden internal wording is absent
- acquisition / cleaning / OCR / desensitization / editing-process wording is absent from recipient-facing正文
- absolute paths such as `/Users/` or `file:///` are absent
- top-level HTML files have usable `<title>` and `<h1>`

Example:

```bash
python3 ~/.codex/skills/formal-delivery-package/scripts/audit_formal_package.py <package_dir> \
  --required index.html \
  --required README.md \
  --required analysis_code/README.md \
  --required analysis_data/README.md \
  --required-text 'README.md::需求方' \
  --required-text 'README.md::分析提供方'
```

## Quick Reference

| Area | Default expectation |
|---|---|
| Package tone | Neutral, formal, recipient-ready |
| Role labels | Include requester / demand side and analysis provider |
| HTML entry | `index.html` should be the default entry page |
| README | Reading order, package contents, code/data note, claim boundary |
| Code bundle | Entrypoint, config, stage scripts, figure scripts |
| Data bundle | Minimal approved inputs supporting included outputs |
| Update strategy | Patch locally first; avoid unnecessary reruns |
| Final step | Rebuild ZIP and audit |

## Common Mistakes

### Mistake: keeping internal wording
Do not ship phrases such as internal handoff labels, teacher-package wording, chatty greetings, escalation notes, or comments explaining internal coordination.

### Mistake: using session, forwarding, or internal-chat wording in Chinese formal packages
Do not title recipient-facing sections as “本次会话报告”, “可直接发送摘要”, or action labels centered on “直接转发” / “内部沟通”. These frame the package like a chat artifact instead of a formal record. Replace them with neutral archival or review wording such as “分析小结”, “分析小结（正式记录）”, “正式查看”, “结果复核”, or “独立结果留档”.

### Mistake: exposing material-processing or desensitization workflow in recipient-facing pages
Do not ship正文 that says how the source was OCR'd, cleaned, desensitized, stripped of names, edited from screenshots, or converted from a long image/post. Phrases such as “基于 OCR 脱敏整理”, “素材清洗后”, “已移除作者名/日期/原始链接”, “本页不复用原始截图” belong to internal notes or provenance logs, not to the formal page the recipient reads first. Replace them with direct content framing such as “本页用于结果说明”, “本页整理当前可直接引用的结果与边界”, or move provenance details into a restricted internal log if they truly must be kept.

### Mistake: omitting requester / provider identity
Formal packages should not force recipients to infer who asked for the work and who produced it.

### Mistake: bundling outputs without code or data context
A polished HTML page without supporting code/data folders is usually not a complete formal delivery package.

### Mistake: upgrading the claim while packaging
Packaging is presentation work. Do not convert internal validation into external validation, exploratory results into confirmed results, or training metrics into test-set claims.

### Mistake: updating the folder but forgetting the ZIP
Always regenerate the archive and verify its contents after modifying the package directory.

## When Not to Use

Do not use this skill for:
- purely internal scratch notes
- manuscript writing without package assembly
- a single standalone chart or memo with no delivery package requirement
- workflows where code/data must never be bundled and a manifest-only handoff is explicitly required

## Resources

- `references/tone-and-structure.md`: preferred formal phrasing, role labels, page naming, README skeleton, and phrases to avoid
- `references/chinese-workflow-templates.md`: Chinese-first README, HTML hero, main report, method note, sensitivity note, and code/data README templates
- `references/package-checklist.md`: file inclusion checklist, package structure expectations, ZIP workflow, and acceptance checklist
- `scripts/audit_formal_package.py`: reusable audit script for required files, required text, forbidden text, absolute paths, and HTML title/h1 checks
