Capture Reusable Value
Core Principle
Preserve reusable value in its cheapest appropriate representation, not everything, and not always a skill. "Nothing worth saving" is a valid, common outcome. This replaces the old capture-after-every-session ritual.
When to Use / NOT
- Use when: the same hard procedure recurred. a failure was expensive to diagnose. a non-obvious edge case will likely recur. a deterministic regression should become a gate. a reusable implementation is worth extracting. an architectural decision should be remembered. the user asks to capture the session's reusable value.
- NOT when: routine sessions, standard PR summaries, generic framework knowledge, anything already obvious from source, no capture ritual after every session. HARD-GATE.
Classification (per candidate)
| Class |
Test |
Where it lands |
| CODE |
Reusable implementation? |
Actual code / library / project template |
| REFERENCE |
Upstream implementation or website worth keeping? |
reference/<repo>/ checkout or reference/web/<site>/ capture per the reference-driven-development contract |
| FOUNDATION |
Reusable architecture/patterns/seams cheaper to retrieve than re-derive? |
skills/<x>-foundation/ (earned; not automatic from every repo) |
| GATE |
Deterministic regression class with low false positives? |
Test / lint / CI check / validator script |
| SKILL |
Repeated procedure or hard-won operational method? |
Skill leaf in the catalog (follows writing-skills) |
| PROJECT NOTE |
Critical rationale, operational constraint, or unresolved decision: expensive to reconstruct and not obvious from source, tests, Git, configuration, or session recall? |
Smallest project-appropriate tracked location |
| NOT WORTH SAVING |
Cheap to rediscover, one-off, temporary |
Nothing, explicitly record the decision |
Route each candidate to the cheapest class that preserves it. Do not force a skill when a gate, a line of code, or a project note does the job. Aesthetic preferences are not gates; only demonstrated regression classes with acceptable false-positive cost become gates.
Threshold questions (all must roughly hold for SKILL, GATE, or FOUNDATION)
- Would this be re-derived at real cost without it?
- Is it stable enough to document (not mid-flip)?
- Is the representation cheaper than the re-derivation?
FOUNDATION promotion: create or expand a foundation only when reusable
architecture, seams, patterns, edge cases, or decisions are expensive enough
to rediscover that preserving them is cheaper than re-derivation. Active owned
projects remain source, not capture candidates. Owned-project promotion
requires an explicit user request after a stable milestone; finishing a project
does not trigger promotion. External implementations remain demand-driven.
Record portable upstream identity and revision so the foundation reconnects to
real source. Mark it kind: foundation, manual, and hidden; keep exhaustive
evidence in skills/<x>-foundation/references/index.md and load one capsule at
a time. A foundation is cold evidence, not an operational procedure; see
../writing-skills/references/foundation-kind.md and
../reference-driven-development/references/contract.md.
Workflow
- Recall evidence from diffs, source, tests, and selected session events. Raw session JSONL already owns history; never re-artifact it.
- Classify possible durable promotions. A reflection may recommend a SKILL candidate, but only explicit
/compile-skill, /compile-session-improvements, or an equivalent direct user request may create it.
- Explicitly drop cheap or one-off material.
- Promote only survivors. Skill candidates follow the catalog authoring rules; gate candidates need a demonstrated regression and a low-false-positive check; foundation candidates follow
../reference-driven-development/references/contract.md provenance rules and land in skills/<x>-foundation/; project notes land in the smallest project-appropriate tracked location.
- Report what was deliberately not saved.
Red Flags
- Capture ritual after every session, PR, or subagent opinion. HARD-GATE.
- Forcing everything into a skill.
- Aesthetic code-taste rules promoted to gates without demonstrated regressions.
- Saving what source/Git/manifests already say.
- Automatically indexing or promoting an active or newly completed owned project.
- Storing historical evidence in a new memory artifact; raw session JSONL already owns history. HARD-GATE.
Verification
Each survivor exists in its claimed form (code compiles/used; gate fails on the regression class and passes clean cases; skill passes the validator; foundation has a manual, hidden, kind: foundation SKILL.md with portable provenance, a complete local reference index, and cited capsules on disk; owned-project promotion records the explicit post-milestone request; project note exists in its tracked location). The not-saved list is explicit.
References
../writing-skills/SKILL.md, skill authoring grammar../writing-skills/references/foundation-kind.md, foundation/procedure boundary../reference-driven-development/references/contract.md, reference-checkout rules../goal-setup/SKILL.md, where earned recovery or handoff state may live
1---2name: leverage-capture3description: Use when capture is explicitly requested, a hard procedure recurs, or an expensive failure or milestone yields a concrete reusable candidate; classify it into code, references, foundations, gates, skills, project notes, or nothing.4---56# Capture Reusable Value78## Core Principle910Preserve reusable value in its cheapest appropriate representation, not everything, and not always a skill. "Nothing worth saving" is a valid, common outcome. This replaces the old capture-after-every-session ritual.1112## When to Use / NOT1314- **Use when:** the same hard procedure recurred. a failure was expensive to diagnose. a non-obvious edge case will likely recur. a deterministic regression should become a gate. a reusable implementation is worth extracting. an architectural decision should be remembered. the user asks to capture the session's reusable value.15- **NOT when:** routine sessions, standard PR summaries, generic framework knowledge, anything already obvious from source, no capture ritual after every session. HARD-GATE.1617## Classification (per candidate)1819| Class | Test | Where it lands |20|---|---|---|21| **CODE** | Reusable implementation? | Actual code / library / project template |22| **REFERENCE** | Upstream implementation or website worth keeping? | `reference/<repo>/` checkout or `reference/web/<site>/` capture per the `reference-driven-development` contract |23| **FOUNDATION** | Reusable architecture/patterns/seams cheaper to retrieve than re-derive? | `skills/<x>-foundation/` (earned; not automatic from every repo) |24| **GATE** | Deterministic regression class with low false positives? | Test / lint / CI check / validator script |25| **SKILL** | Repeated procedure or hard-won operational method? | Skill leaf in the catalog (follows `writing-skills`) |26| **PROJECT NOTE** | Critical rationale, operational constraint, or unresolved decision: expensive to reconstruct and not obvious from source, tests, Git, configuration, or session recall? | Smallest project-appropriate tracked location |27| **NOT WORTH SAVING** | Cheap to rediscover, one-off, temporary | Nothing, explicitly record the decision |2829Route each candidate to the *cheapest* class that preserves it. Do not force a skill when a gate, a line of code, or a project note does the job. Aesthetic preferences are not gates; only demonstrated regression classes with acceptable false-positive cost become gates.3031## Threshold questions (all must roughly hold for SKILL, GATE, or FOUNDATION)32331. Would this be re-derived at real cost without it?342. Is it stable enough to document (not mid-flip)?353. Is the representation cheaper than the re-derivation?3637**FOUNDATION promotion:** create or expand a foundation only when reusable38architecture, seams, patterns, edge cases, or decisions are expensive enough39to rediscover that preserving them is cheaper than re-derivation. Active owned40projects remain source, not capture candidates. Owned-project promotion41requires an explicit user request after a stable milestone; finishing a project42does not trigger promotion. External implementations remain demand-driven.43Record portable upstream identity and revision so the foundation reconnects to44real source. Mark it `kind: foundation`, manual, and hidden; keep exhaustive45evidence in `skills/<x>-foundation/references/index.md` and load one capsule at46a time. A foundation is cold evidence, not an operational procedure; see47`../writing-skills/references/foundation-kind.md` and48`../reference-driven-development/references/contract.md`.4950## Workflow51521. Recall evidence from diffs, source, tests, and selected session events. Raw session JSONL already owns history; never re-artifact it.532. Classify possible durable promotions. A reflection may recommend a SKILL candidate, but only explicit `/compile-skill`, `/compile-session-improvements`, or an equivalent direct user request may create it.543. Explicitly drop cheap or one-off material.554. Promote only survivors. Skill candidates follow the catalog authoring rules; gate candidates need a demonstrated regression and a low-false-positive check; foundation candidates follow `../reference-driven-development/references/contract.md` provenance rules and land in `skills/<x>-foundation/`; project notes land in the smallest project-appropriate tracked location.565. Report what was deliberately not saved.5758## Red Flags5960- Capture ritual after every session, PR, or subagent opinion. HARD-GATE.61- Forcing everything into a skill.62- Aesthetic code-taste rules promoted to gates without demonstrated regressions.63- Saving what source/Git/manifests already say.64- Automatically indexing or promoting an active or newly completed owned project.65- Storing historical evidence in a new memory artifact; raw session JSONL already owns history. HARD-GATE.6667## Verification6869Each survivor exists in its claimed form (code compiles/used; gate fails on the regression class and passes clean cases; skill passes the validator; foundation has a manual, hidden, `kind: foundation` SKILL.md with portable provenance, a complete local reference index, and cited capsules on disk; owned-project promotion records the explicit post-milestone request; project note exists in its tracked location). The not-saved list is explicit.7071## References7273- `../writing-skills/SKILL.md`, skill authoring grammar74- `../writing-skills/references/foundation-kind.md`, foundation/procedure boundary75- `../reference-driven-development/references/contract.md`, reference-checkout rules76- `../goal-setup/SKILL.md`, where earned recovery or handoff state may live
ryan-brosas