sprngr/rubber-duck / src/skills/duck-tape
duck-tape
VerifiedTwo-tier session memory: CONTEXT.md (persistent) + .duck-tape working state, with merge/dedupe. Subcommands: merge, resume, init, prune, migrate. Use when: "duck-tape", "compact session", "update CONTEXT.md", "resume session".
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 15.5 KB |
| SKILL.md | skill md | 14.4 KB |
| examples/CHANGELOG.md | markdown | 419 B |
| examples/CONTEXT.md | markdown | 2.1 KB |
| examples/STATE.md | markdown | 1.2 KB |
| examples/bootstrap-CONTEXT.md | markdown | 463 B |
| hooks/claude-code.hooks.json | config | 291 B |
| hooks/claude-code.hooks.windows.json | config | 312 B |
| hooks/copilot.hooks.json | config | 325 B |
| hooks/extract-raw.ps1 | script | 15.2 KB |
| hooks/extract-raw.shexecutable | script | 12.2 KB |
| hooks/extract-state.ps1 | script | 15.1 KB |
| hooks/extract-state.shexecutable | script | 11.3 KB |
| hooks/opencode.plugin.js | script | 12.9 KB |
| hooks/pre-compact.ps1 | script | 1.1 KB |
| hooks/pre-compact.shexecutable | script | 1.0 KB |
| references/HOOKS_GUIDE.md | markdown | 11.3 KB |
| references/OUTPUT_SCHEMA.md | markdown | 3.8 KB |
| references/SCHEMA.md | markdown | 7.0 KB |
| references/STATE_SCHEMA.md | markdown | 5.7 KB |
references/SCHEMA.md
View on GitHub# CONTEXT.md Schema
## Sections
The file opens with a top-level title (`# <name>`) followed by a Table of Contents. The 7 fixed sections follow.
### 0. Table of Contents (Contents)
Second block in the file, directly under the title. Lists the 7 fixed sections with anchor links.
```
# <Project Context title>
## Contents
- [Goals](#goals)
- [Decisions](#decisions)
- [Conventions](#conventions)
- [Glossary](#glossary)
- [Deferred-Debt](#deferred-debt)
- [Open-Questions](#open-questions)
- [Notes](#notes)
## Goals
...
```
Heading is `## Contents` to match the fixed-section heading level. TOC is the only addition above Goals.
Merge:
- Bootstrap: generate TOC from the 7 section headers after first write.
- Merge: regenerate TOC if the set of `##` section headings changes (rare). Otherwise leave existing TOC untouched.
- Migrate: generate TOC after section headers appended to restructured file.
### 1. Goals
What the project optimizes for. Keyed by goal name.
```
## Goals
- **<name>**: <what we optimize for>
```
Merge:
- Dedupe by name.
- Supersede on conflict.
- Append new.
### 2. Decisions
Explicit decisions made in session. Keyed by decision name.
```
## Decisions
- **<name>**: <decision> (date: <YYYY-MM-DD>)
```
Merge:
- Dedupe by name.
- On conflict: supersede. Old entry archived to changelog. New entry replaces.
- Append new names.
### 3. Conventions
Project-local conventions and patterns, keyed by convention name; exclude agent operating policy (for example safety gates, approval workflow, and hard behavioral constraints).
```
## Conventions
- **<name>**: <convention>
```
Merge:
- Dedupe by name.
- Supersede on conflict.
- Append new.
### 4. Glossary
Domain terms and definitions. Keyed by term.
```
## Glossary
- **<term>**: <definition>
```
Merge:
- Dedupe by term.
- Supersede on conflict.
- Append new.
### 5. Deferred-Debt
Deferred work and decisions. Append-only with status markers.
```
## Deferred-Debt
- TODO(<debt type>): <date> <what deferred> [status: open|resolved]
- TODO(<debt type>,#<issue>): <date> <what> [resolved: <decision>]
```
Merge:
- Append new. If an entry needs modification, apply a status update only — keep the original line.
- Status update: append resolution marker, keep original line.
### 6. Open-Questions
Unresolved questions. Append new.
```
## Open-Questions
- <question> (date: <YYYY-MM-DD>)
```
Merge:
- Append new questions.
- Dedupe by question text (normalized whitespace).
- Drop resolved questions at merge time. Resolution captured in Decisions or Notes.
### 7. Notes
User-defined freeform content. Timestamped append-only.
```
## Notes
### <YYYY-MM-DD HH:MM>
<freeform content>
```
Merge:
- Append new timestamped block at end.
- If a block exists, append a new timestamped block; do not rewrite existing ones.
- Prune via `/duck-tape prune` only.
- Status detail (blockers, in-progress detail, next-up) belongs in Notes subsection `### Status`. Uses Notes append-only semantics.
## Merge Algorithm
Merge input is translated from session state file (`.duck-tape/<id>.state.md`), not raw session content. Translation uses rigid map in `references/STATE_SCHEMA.md`. See that file for state-section to CONTEXT.md-section mapping.
0. **Redact incoming state content** before translation + merge:
- Scan for secrets/PII: API keys, passwords, tokens, connection strings, env var values, personally identifiable information.
- On detection: reject flagged content. Report findings. Ask user to redact source or confirm mask-in-place (`<REDACTED>`).
- If a merge would place raw secrets into CONTEXT.md, reject it; merge masked content only after user confirmation.
- Applies to all sections including Notes freeform.
1. Parse existing CONTEXT.md into sections by `##` headers.
2. Translate redacted state file into CONTEXT.md sections using rigid map in `references/STATE_SCHEMA.md`. Parse subsections within each top-level section by `###` headers.
3. Apply the durable-context filter before translation:
- Keep durable decisions, constraints, conventions, glossary facts, deferred debt, and open questions.
- Drop development narration, rejected approaches, recent-change context, session-only approval flags, and review/test/session references that only describe how work was produced.
- Keep test or review references only when they state a durable verification requirement.
- Keep historical rationale in ADRs or changelogs, not ordinary CONTEXT.md entries.
- If filtered content contains a durable decision or constraint, preserve that underlying content without the session history.
4. Summarize translated content to persistent-context granularity. State file detail (commands, hashes, raw output) stays in state file. CONTEXT.md receives decision-level summary. This is granularity reduction, not rewrite or interpretation. Facts preserved. Detail dropped.
5. Per section, apply merge rules above.
6. Generate changelog:
- `Added: <section> <key>`
- `Superseded: <section> <key> (<old> -> <new>)`
- `Dropped: <section> <key> (<reason>)`
7. Write merged CONTEXT.md.
8. Emit changelog to user.
## Conflict Resolution
Conflict = same key exists in existing and incoming with different values.
- Decisions/Conventions/Glossary: incoming supersedes existing. Session content is newer truth.
- Goals: incoming supersedes existing. Session content is newer truth.
- Deferred-Debt: no conflict possible (append-only with status).
- Open-Questions: no supersede. Resolved questions dropped at merge; resolution already captured in Decisions or Notes.
- Notes: no conflict possible (append-only).
## Subsection Merge Rules
Top-level sections may contain `###` subsections for visual grouping. Subsections are presentational. Merge operates at key level within each top-level section.
- Keys dedupe across all subsections within a top-level section. Same key in different subsections is a conflict. Supersede per section rules.
- Entries merge into existing subsections by key. If key exists in `### Routing`, incoming supersedes in place.
- New subsections (not present in existing file) appended at end of top-level section with their entries.
- Subsection headers preserved as-is. If a subsection exists, keep its name and position; do not rename or reorder.
- Subsection position of new entries follows: existing key -> merge in place within its subsection. New key with no existing subsection match -> append to the subsection that contains it in incoming. If incoming subsection is new -> append entire subsection to end of top-level section.
## Missing Sections
If existing CONTEXT.md lacks one or more schema sections:
1. Abort merge.
2. Report missing sections to user.
3. Prompt: "CONTEXT.md lacks schema sections: <list>. Run /duck-tape migrate to add empty sections before merge."
4. Do not infer or auto-add sections silently.
Migration (`/duck-tape migrate` — defined in SKILL.md) appends missing section headers + bootstrap markers to existing file. Preserves all existing content above appended sections. Generates TOC after section headers appended. Requires execution approval per SKILL.md Migrate section.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |