Experience Pack
One sentence: every project keeps its own experience ledger; a boundary test
distills the portable part; only the portable part travels between projects.
The two layers
| Layer |
File |
Owner |
Content rules |
| Ledger |
EXPERIENCE.md in the project root |
the project |
dated, concrete, project specifics allowed; process experience only — never product truth, never a decision register |
| Portable |
the project's portable-lessons file (e.g. LESSONS.md) and/or this skill's reference pack |
travels |
abstract, product-noun-free, true in a DIFFERENT project read by a stranger |
Pipeline: something happens → ledger entry (same day, while it hurts) →
periodic distillation pass → portable lessons. Strategy and product decisions
never travel: experience inherits, decisions die.
Protocol A — RECORD (ledger)
Create EXPERIENCE.md at the project root on day one (or on first use).
Append an entry when any of these happen: an incident cost real time/money/
trust; a method visibly worked; an independent reviewer caught something the
author missed; a collaboration pattern succeeded or failed; the user corrected
the agent's course.
Entry format:
### YYYY-MM-DD — title
**What happened:** facts, concrete.
**What we did:** the response, concrete.
**What worked / what failed:** both, honestly.
**Cost:** time / tokens / trust / rework.
**Portable?** yes → <lesson-slug> | not yet | no (project-specific).
Rules: record process experience, not product facts; if the workspace has
contamination-hygiene rules (banned nouns), the ledger obeys them; never
backdate or rewrite old entries — append corrections as new entries.
Binding rules (added 2026-07-18, distilled from the second adopter project):
- Recording is part of done. An incident's fix may not be declared complete
until its ledger entry exists — the ledger is a gate, not a diary. (Its first
adopter backfilled 8 entries in one day because nothing forced writing at
incident time; firefights never leave time for diaries.)
- Bootstrap imports are legitimate, silent backdating is not. When adopting
the pack on a project with history: date each entry by its INCIDENT date and
declare the import in a dated note at the top of the ledger. An entry dated in
the past without a declared import is fabrication.
- Distribution hygiene. The ledger contains project internals. In a repo
with a public remote, gitignore
EXPERIENCE.md by default; publish only the
boundary-tested portable layer.
- Discoverability. Add one pointer line to the project's primary truth file
(CLAUDE.md / system map / state doc) so a zero-context agent can FIND the
ledger; an undiscoverable ledger records nothing for the next session.
Protocol B — DISTILL (boundary test)
For each ledger entry marked "Portable? yes/not yet", run the tests in order:
- Substitution test — strip every proper noun and specific number. Does
the statement still teach something? Collapses → it is a decision, dies.
- Mechanism vs choice — does it say how things work or fail (mechanism →
inherit), or who/what/how much was chosen (choice → dies)?
- Re-derivation test — could a smart stranger re-derive it from the new
project's own context? If it could only come from the old project's
strategy, it is the old strategy talking — dies.
- Sunk-cost test — is its only value that effort was spent on it? Dies.
- Verifiability test — does checking it require a dead noun? Abstract it
or let it die.
Survivors are rewritten as one abstract imperative line + why + how to apply,
tagged with provenance ("prior project, distilled · date"). Write the portable
layer in English (or bilingually): the ledger may use any language the project
lives in, but portable lessons travel to strangers — project-local idiom
strands them. Ambiguous items
default to DIE — the ledger keeps them recoverable for a later pass.
DOWNGRADE (rare): a strategy-shaped artifact re-enters another project only as
an explicit HYPOTHESIS with a re-validation condition, and only by the user's
call — never silently.
Protocol C — SHARE / APPLY (another project learns from this one)
- In the receiving project: read
references/rebuild-experience-pack.md
(this skill's packaged saga) and/or the source project's portable-lessons
file — never the source project's ledger, truth files, or strategy.
- Bootstrap the receiving project's own
EXPERIENCE.md (Protocol A).
- Walk the pack's five advices as a setup checklist; adopt what applies;
record deviations as the receiving project's first ledger entry.
- Adopted lessons enter the receiving project tagged with provenance; they
are engineering constraints, not user decisions — the user may re-class
any of them.
Boundaries — what this skill never does
- Never copies strategy, product facts, personas, pricing, channels, client
names, or account identities between projects — in either direction.
- Never treats the ledger as a decision register; decisions live in the
project's own truth/decision files with their own provenance rules.
- Never edits other skills or the user's global config.
- Never reads a project's quarantined/archived material to "enrich" a pack;
distillation input is the ledger and the live files only.
Relationship to adjacent skills
- iteration-close — closes an iteration of a continuing direction (distill,
delete baggage, tag, seed). Run experience-pack's Protocol B as part of it if
both are installed; iteration-close owns the closure ritual. Caveat both
skills must honor: "git history is the archive" holds ONLY for tracked
files. Untracked/gitignored material (private IP in a public repo) has no
archive — quarantine it under an explicit local rule (e.g.
_retired/)
before any purge; deleting it is permanent loss, not cleanup.
- Decontamination / fresh-start skills — when a direction is REPLACED, the
boundary test here is the same test used to decide what survives; the
decontamination skill owns the purge mechanics.
- This skill is product-agnostic and must stay that way: if a project's noun
ever appears in this file or its references, that is a defect — remove it.
Reference
references/rebuild-experience-pack.md — the packaged, noun-free experience
from a real five-rebuild contamination saga: the six contamination doors, the
source-lock reset method, the three-probe verification stack, the multi-AI
collaboration protocol, and the five prevention advices.
1---2name: experience-pack-23description: "Two-layer experience system for any project: keep a per-project EXPERIENCE.md ledger (dated entries: what happened, what we did, what it cost), then distill it through an experience-vs-decision boundary test into portable, noun-free lessons that other projects can safely reuse — experience inherits, decisions die. Ships a reference pack distilled from a real 5-rebuild contamination saga (source-lock bundles, planner/executor/ verifier role isolation, zero-context probes, quarantined banned-noun lists, bounded repair loops, multi-AI reference-not-instruction triage) plus five prevention advices. Use when the user says 经验包 / 记录经验 / 复盘 / 经验文件 / 沉淀经验 / experience pack / lessons learned / post-mortem / record this experience / distill experience / \"what did we learn\" / wants a project to learn from another project's history, or after any expensive incident worth recording. NOT for closing an iteration (use iteration-close) and NOT a decision register — decisions stay in the project's own truth files."4---56# Experience Pack78One sentence: every project keeps its own experience ledger; a boundary test9distills the portable part; only the portable part travels between projects.1011## The two layers1213| Layer | File | Owner | Content rules |14|---|---|---|---|15| Ledger | `EXPERIENCE.md` in the project root | the project | dated, concrete, project specifics allowed; process experience only — never product truth, never a decision register |16| Portable | the project's portable-lessons file (e.g. `LESSONS.md`) and/or this skill's reference pack | travels | abstract, product-noun-free, true in a DIFFERENT project read by a stranger |1718Pipeline: something happens → ledger entry (same day, while it hurts) →19periodic distillation pass → portable lessons. Strategy and product decisions20never travel: **experience inherits, decisions die.**2122## Protocol A — RECORD (ledger)2324Create `EXPERIENCE.md` at the project root on day one (or on first use).25Append an entry when any of these happen: an incident cost real time/money/26trust; a method visibly worked; an independent reviewer caught something the27author missed; a collaboration pattern succeeded or failed; the user corrected28the agent's course.2930Entry format:3132```33### YYYY-MM-DD — title34**What happened:** facts, concrete.35**What we did:** the response, concrete.36**What worked / what failed:** both, honestly.37**Cost:** time / tokens / trust / rework.38**Portable?** yes → <lesson-slug> | not yet | no (project-specific).39```4041Rules: record process experience, not product facts; if the workspace has42contamination-hygiene rules (banned nouns), the ledger obeys them; never43backdate or rewrite old entries — append corrections as new entries.4445Binding rules (added 2026-07-18, distilled from the second adopter project):4647- **Recording is part of done.** An incident's fix may not be declared complete48 until its ledger entry exists — the ledger is a gate, not a diary. (Its first49 adopter backfilled 8 entries in one day because nothing forced writing at50 incident time; firefights never leave time for diaries.)51- **Bootstrap imports are legitimate, silent backdating is not.** When adopting52 the pack on a project with history: date each entry by its INCIDENT date and53 declare the import in a dated note at the top of the ledger. An entry dated in54 the past without a declared import is fabrication.55- **Distribution hygiene.** The ledger contains project internals. In a repo56 with a public remote, gitignore `EXPERIENCE.md` by default; publish only the57 boundary-tested portable layer.58- **Discoverability.** Add one pointer line to the project's primary truth file59 (CLAUDE.md / system map / state doc) so a zero-context agent can FIND the60 ledger; an undiscoverable ledger records nothing for the next session.6162## Protocol B — DISTILL (boundary test)6364For each ledger entry marked "Portable? yes/not yet", run the tests in order:65661. **Substitution test** — strip every proper noun and specific number. Does67 the statement still teach something? Collapses → it is a decision, dies.682. **Mechanism vs choice** — does it say how things work or fail (mechanism →69 inherit), or who/what/how much was chosen (choice → dies)?703. **Re-derivation test** — could a smart stranger re-derive it from the new71 project's own context? If it could only come from the old project's72 strategy, it is the old strategy talking — dies.734. **Sunk-cost test** — is its only value that effort was spent on it? Dies.745. **Verifiability test** — does checking it require a dead noun? Abstract it75 or let it die.7677Survivors are rewritten as one abstract imperative line + why + how to apply,78tagged with provenance ("prior project, distilled · date"). Write the portable79layer in English (or bilingually): the ledger may use any language the project80lives in, but portable lessons travel to strangers — project-local idiom81strands them. Ambiguous items82default to DIE — the ledger keeps them recoverable for a later pass.83DOWNGRADE (rare): a strategy-shaped artifact re-enters another project only as84an explicit HYPOTHESIS with a re-validation condition, and only by the user's85call — never silently.8687## Protocol C — SHARE / APPLY (another project learns from this one)88891. In the receiving project: read `references/rebuild-experience-pack.md`90 (this skill's packaged saga) and/or the source project's portable-lessons91 file — never the source project's ledger, truth files, or strategy.922. Bootstrap the receiving project's own `EXPERIENCE.md` (Protocol A).933. Walk the pack's **five advices** as a setup checklist; adopt what applies;94 record deviations as the receiving project's first ledger entry.954. Adopted lessons enter the receiving project tagged with provenance; they96 are engineering constraints, not user decisions — the user may re-class97 any of them.9899## Boundaries — what this skill never does100101- Never copies strategy, product facts, personas, pricing, channels, client102 names, or account identities between projects — in either direction.103- Never treats the ledger as a decision register; decisions live in the104 project's own truth/decision files with their own provenance rules.105- Never edits other skills or the user's global config.106- Never reads a project's quarantined/archived material to "enrich" a pack;107 distillation input is the ledger and the live files only.108109## Relationship to adjacent skills110111- **iteration-close** — closes an iteration of a continuing direction (distill,112 delete baggage, tag, seed). Run experience-pack's Protocol B as part of it if113 both are installed; iteration-close owns the closure ritual. **Caveat both114 skills must honor:** "git history is the archive" holds ONLY for tracked115 files. Untracked/gitignored material (private IP in a public repo) has no116 archive — quarantine it under an explicit local rule (e.g. `_retired/`)117 before any purge; deleting it is permanent loss, not cleanup.118- **Decontamination / fresh-start skills** — when a direction is REPLACED, the119 boundary test here is the same test used to decide what survives; the120 decontamination skill owns the purge mechanics.121- This skill is product-agnostic and must stay that way: if a project's noun122 ever appears in this file or its references, that is a defect — remove it.123124## Reference125126`references/rebuild-experience-pack.md` — the packaged, noun-free experience127from a real five-rebuild contamination saga: the six contamination doors, the128source-lock reset method, the three-probe verification stack, the multi-AI129collaboration protocol, and the five prevention advices.