Publish Sign in

Compound Refresh

Refresh stale or drifting learnings and pattern docs in docs/solutions/ by reviewing, updating, consolidating, replacing, or deleting them…

You say
Install this skill Read the source first Free Written by EveryInc · unverified publisher
Context cost
12.3k tokensestimated from the bundle, loaded when it triggers
Bundle
4 files · 49.4 kBtext throughout, nothing executable
Licence
MITfree to use
Last change
—no release on file
Servers it uses
Noneruns standalone

What it does

Refresh stale or drifting learnings and pattern docs in docs/solutions/ by reviewing, updating, consolidating, replacing, or deleting them against the current codebase. Use after refactors, migrations, dependency upgrades, or when a retrieved learning feels outdated or wrong. Also use when reviewing docs/solutions/ for accuracy, when a recently solved problem contradicts an existing learning, when pattern docs no longer reflect current code, or when multiple docs seem to cover the same topic and might benefit from consolidation.

Installed, it changes the agent in these ways.

What this skill changes about the agent is not written down here yet. The listing was collected from its source, and the description is in its own SKILL.md.

Workflow

Runs a procedure end to end.

documentation
Filed under

Learning & Documentation

The skill itself

This is the whole product. A skill is instructions the model reads, so there is nothing behind the listing you cannot see first — the front matter loads with every session, and the body below it loads when the skill triggers.

SKILL.md42.8 kB · 645 lines
--- name: ce:compound-refresh description: Refresh stale or drifting learnings and pattern docs in docs/solutions/ by reviewing, updating, consolidating, replacing, or deleting them against the current codebase. Use after refactors, migrations, dependency upgrades, or when a retrieved learning feels outdated or wrong. Also use when reviewing docs/solutions/ for accuracy, when a recently solved problem contradicts an existing learning, when pattern docs no longer reflect current code, or when multiple docs seem to cover the same topic and might benefit from consolidation. argument-hint: "[mode:autofix] [optional: scope hint]" disable-model-invocation: true ---
8# Compound Refresh
9
10Maintain the quality of docs/solutions/ over time. This workflow reviews existing learnings against the current codebase, then refreshes any derived pattern docs that depend on them.
11
12## Mode Detection
13
14Check if $ARGUMENTS contains mode:autofix. If present, strip it from arguments (use the remainder as a scope hint) and run in **autofix mode**.
15
16| Mode | When | Behavior |
17|------|------|----------|
18| **Interactive** (default) | User is present and can answer questions | Ask for decisions on ambiguous cases, confirm actions |
19| **Autofix** | mode:autofix in arguments | No user interaction. Apply all unambiguous actions (Keep, Update, Consolidate, auto-Delete, Replace with sufficient evidence). Mark ambiguous cases as stale. Generate a summary report at the end. |
20
21### Autofix mode rules
22
23- **Skip all user questions.** Never pause for input.
24- **Process all docs in scope.** No scope narrowing questions — if no scope hint was provided, process everything.
25- **Attempt all safe actions:** Keep (no-op), Update (fix references), Consolidate (merge and delete subsumed doc), auto-Delete (unambiguous criteria met), Replace (when evidence is sufficient). If a write succeeds, record it as **applied**. If a write fails (e.g., permission denied), record the action as **recommended** in the report and continue — do not stop or ask for permissions.
26- **Mark as stale when uncertain.** If classification is genuinely ambiguous (Update vs Replace vs Consolidate vs Delete) or Replace evidence is insufficient, mark as stale with status: stale, stale_reason, and stale_date in the frontmatter. If even the stale-marking write fails, include it as a recommendation.
27- **Use conservative confidence.** In interactive mode, borderline cases get a user question. In autofix mode, borderline cases get marked stale. Err toward stale-marking over incorrect action.
28- **Always generate a report.** The report is the primary deliverable. It has two sections: **Applied** (actions that were successfully written) and **Recommended** (actions that could not be written, with full rationale so a human can apply them or run the skill interactively). The report structure is the same regardless of what permissions were granted — the only difference is which section each action lands in.
29
30## Interaction Principles
31
32**These principles apply to interactive mode only. In autofix mode, skip all user questions and apply the autofix mode rules above.**
33
34Follow the same interaction style as ce:brainstorm:
35
36- Ask questions **one at a time** — use the platform's blocking question tool when available (AskUserQuestion in Claude Code, request_user_input in Codex, ask_user in Gemini). Otherwise, present numbered options in plain text and wait for the user's reply before continuing
37- Prefer **multiple choice** when natural options exist
38- Start with **scope and intent**, then narrow only when needed
39- Do **not** ask the user to make decisions before you have evidence
40- Lead with a recommendation and explain it briefly
41
42The goal is not to force the user through a checklist. The goal is to help them make a good maintenance decision with the smallest amount of friction.
43
44## Refresh Order
45
46Refresh in this order:
47
481. Review the relevant individual learning docs first
492. Note which learnings stayed valid, were updated, were consolidated, were replaced, or were deleted
503. Then review any pattern docs that depend on those learnings
51
52Why this order:
53
54- learning docs are the primary evidence
55- pattern docs are derived from one or more learnings
56- stale learnings can make a pattern look more valid than it really is
57
58If the user starts by naming a pattern doc, you may begin there to understand the concern, but inspect the supporting learning docs before changing the pattern.
59
60## Maintenance Model
61
62For each candidate artifact, classify it into one of five outcomes:
63
64| Outcome | Meaning | Default action |
65|---------|---------|----------------|
66| **Keep** | Still accurate and still useful | No file edit by default; report that it was reviewed and remains trustworthy |
67| **Update** | Core solution is still correct, but references drifted | Apply evidence-backed in-place edits |
68| **Consolidate** | Two or more docs overlap heavily but are both correct | Merge unique content into the canonical doc, delete the subsumed doc |
69| **Replace** | The old artifact is now misleading, but there is a known better replacement | Create a trustworthy successor, then delete the old artifact |
70| **Delete** | No longer useful, applicable, or distinct | Delete the file — git history preserves it if anyone needs to recover it later |
71
72## Core Rules
73
741. **Evidence informs judgment.** The signals below are inputs, not a mechanical scorecard. Use engineering judgment to decide whether the artifact is still trustworthy.
752. **Prefer no-write Keep.** Do not update a doc just to leave a review breadcrumb.
763. **Match docs to reality, not the reverse.** When current code differs from a learning, update the learning to reflect the current code. The skill's job is doc accuracy, not code review — do not ask the user whether code changes were "intentional" or "a regression." If the code changed, the doc should match. If the user thinks the code is wrong, that is a separate concern outside this workflow.
774. **Be decisive, minimize questions.** When evidence is clear (file renamed, class moved, reference broken), apply the update. In interactive mode, only ask the user when the right action is genuinely ambiguous. In autofix mode, mark ambiguous cases as stale instead of asking. The goal is automated maintenance with human oversight on judgment calls, not a question for every finding.
785. **Avoid low-value churn.** Do not edit a doc just to fix a typo, polish wording, or make cosmetic changes that do not materially improve accuracy or usability.
796. **Use Update only for meaningful, evidence-backed drift.** Paths, module names, related links, category metadata, code snippets, and clearly stale wording are fair game when fixing them materially improves accuracy.
807. **Use Replace only when there is a real replacement.** That means either:
81 - the current conversation contains a recently solved, verified replacement fix, or
82 - the user has provided enough concrete replacement context to document the successor honestly, or
83 - the codebase investigation found the current approach and can document it as the successor, or
84 - newer docs, pattern docs, PRs, or issues provide strong successor evidence.
858. **Delete when the code is gone.** If the referenced code, controller, or workflow no longer exists in the codebase and no successor can be found, delete the file — don't default to Keep just because the general advice is still "sound." A learning about a deleted feature misleads readers into thinking that feature still exists. When in doubt between Keep and Delete, ask the user (in interactive mode) or mark as stale (in autofix mode). But missing referenced files with no matching code is **not** a doubt case — it is strong, unambiguous Delete evidence. Auto-delete it.
869. **Evaluate document-set design, not just accuracy.** In addition to checking whether each doc is accurate, evaluate whether it is still the right unit of knowledge. If two or more docs overlap heavily, determine whether they should remain separate, be cross-scoped more clearly, or be consolidated into one canonical document. Redundant docs are dangerous because they drift silently — two docs saying the same thing will eventually say different things.
8710. **Delete, don't archive.** There is no _archived/ directory. When a doc is no longer useful, delete it. Git history preserves every deleted file — that is the archive. A dedicated archive directory creates problems: archived docs accumulate, pollute search results, and nobody reads them. If someone needs a deleted doc, git log --diff-filter=D -- docs/solutions/ will find it.
88
89## Scope Selection
90
91Start by discovering learnings and pattern docs under docs/solutions/.
92
93Exclude:
94
95- README.md
96- docs/solutions/_archived/ (legacy — if this directory exists, flag it for cleanup in the report)
97
98Find all .md files under docs/solutions/, excluding README.md files and anything under _archived/. If an _archived/ directory exists, note it in the report as a legacy artifact that should be cleaned up (files either restored or deleted).
99
100If $ARGUMENTS is provided, use it to narrow scope before proceeding. Try these matching strategies in order, stopping at the first that produces results:
101
1021. **Directory match** — check if the argument matches a subdirectory name under docs/solutions/ (e.g., performance-issues, database-issues)
1032. **Frontmatter match** — search module, component, or tags fields in learning frontmatter for the argument
1043. **Filename match** — match against filenames (partial matches are fine)
1054. **Content search** — search file contents for the argument as a keyword (useful for feature names or feature areas)
106
107If no matches are found, report that and ask the user to clarify. In autofix mode, report the miss and stop — do not guess at scope.
108
109If no candidate docs are found, report:
110
111```text
112No candidate docs found in docs/solutions/.
113Run ce:compound after solving problems to start building your knowledge base.
114```
115
116## Phase 0: Assess and Route
117
118Before asking the user to classify anything:
119
1201. Discover candidate artifacts
1212. Estimate scope
1223. Choose the lightest interaction path that fits
123
124### Route by Scope
125
126| Scope | When to use it | Interaction style |
127|-------|----------------|-------------------|
128| **Focused** | 1-2 likely files or user named a specific doc | Investigate directly, then present a recommendation |
129| **Batch** | Up to ~8 mostly independent docs | Investigate first, then present grouped recommendations |
130| **Broad** | 9+ docs, ambiguous, or repo-wide stale-doc sweep | Triage first, then investigate in batches |
131
132### Broad Scope Triage
133
134When scope is broad (9+ candidate docs), do a lightweight triage before deep investigation:
135
1361. **Inventory** — read frontmatter of all candidate docs, group by module/component/category
1372. **Impact clustering** — identify areas with the densest clusters of learnings + pattern docs. A cluster of 5 learnings and 2 patterns covering the same module is higher-impact than 5 isolated single-doc areas, because staleness in one doc is likely to affect the others.
1383. **Spot-check drift** — for each cluster, check whether the primary referenced files still exist. Missing references in a high-impact cluster = strongest signal for where to start.
1394. **Recommend a starting area** — present the highest-impact cluster with a brief rationale and ask the user to confirm or redirect. In autofix mode, skip the question and process all clusters in impact order.
140
141Example:
142
143```text
144Found 24 learnings across 5 areas.
145
146The auth module has 5 learnings and 2 pattern docs that cross-reference
147each other — and 3 of those reference files that no longer exist.
148I'd start there.
149
1501. Start with auth (recommended)
1512. Pick a different area
1523. Review everything
153```
154
155Do not ask action-selection questions yet. First gather evidence.
156
157## Phase 1: Investigate Candidate Learnings
158
159For each learning in scope, read it, cross-reference its claims against the current codebase, and form a recommendation.
160
161A learning has several dimensions that can independently go stale. Surface-level checks catch the obvious drift, but staleness often hides deeper:
162
163- **References** — do the file paths, class names, and modules it mentions still exist or have they moved?
164- **Recommended solution** — does the fix still match how the code actually works today? A renamed file with a completely different implementation pattern is not just a path update.
165- **Code examples** — if the learning includes code snippets, do they still reflect the current implementation?
166- **Related docs** — are cross-referenced learnings and patterns still present and consistent?
167- **Auto memory** — does the auto memory directory contain notes in the same problem domain? Read MEMORY.md from the auto memory directory (the path is known from the system prompt context). If it does not exist or is empty, skip this dimension. A memory note describing a different approach than what the learning recommends is a supplementary drift signal.
168- **Overlap** — while investigating, note when another doc in scope covers the same problem domain, references the same files, or recommends a similar solution. For each overlap, record: the two file paths, which dimensions overlap (problem, solution, root cause, files, prevention), and which doc appears broader or more current. These signals feed Phase 1.75 (Document-Set Analysis).
169
170Match investigation depth to the learning's specificity — a learning referencing exact file paths and code snippets needs more verification than one describing a general principle.
171
172### Drift Classification: Update vs Replace
173
174The critical distinction is whether the drift is **cosmetic** (references moved but the solution is the same) or **substantive** (the solution itself changed):
175
176- **Update territory** — file paths moved, classes renamed, links broke, metadata drifted, but the core recommended approach is still how the code works. ce:compound-refresh fixes these directly.
177- **Replace territory** — the recommended solution conflicts with current code, the architectural approach changed, or the pattern is no longer the preferred way. This means a new learning needs to be written. A replacement subagent writes the successor following ce:compound's document format (frontmatter, problem, root cause, solution, prevention), using the investigation evidence already gathered. The orchestrator does not rewrite learnings inline — it delegates to a subagent for context isolation.
178
179**The boundary:** if you find yourself rewriting the solution section or changing what the learning recommends, stop — that is Replace, not Update.
180
181**Memory-sourced drift signals** are supplementary, not primary. A memory note describing a different approach does not alone justify Replace or Delete. Use memory signals to:
182- Corroborate codebase-sourced drift (strengthens the case for Replace)
183- Prompt deeper investigation when codebase evidence is borderline
184- Add context to the evidence report ("(auto memory [claude]) notes suggest approach X may have changed since this learning was written")
185
186In autofix mode, memory-only drift (no codebase corroboration) should result in stale-marking, not action.
187
188### Judgment Guidelines
189
190Three guidelines that are easy to get wrong:
191
1921. **Contradiction = strong Replace signal.** If the learning's recommendation conflicts with current code patterns or a recently verified fix, that is not a minor drift — the learning is actively misleading. Classify as Replace.
1932. **Age alone is not a stale signal.** A 2-year-old learning that still matches current code is fine. Only use age as a prompt to inspect more carefully.
1943. **Check for successors before deleting.** Before recommending Replace or Delete, look for newer learnings, pattern docs, PRs, or issues covering the same problem space. If successor evidence exists, prefer Replace over Delete so readers are directed to the newer guidance.
195
196## Phase 1.5: Investigate Pattern Docs
197
198After reviewing the underlying learning docs, investigate any relevant pattern docs under docs/solutions/patterns/.
199
200Pattern docs are high-leverage — a stale pattern is more dangerous than a stale individual learning because future work may treat it as broadly applicable guidance. Evaluate whether the generalized rule still holds given the refreshed state of the learnings it depends on.
201
202A pattern doc with no clear supporting learnings is a stale signal — investigate carefully before keeping it unchanged.
203
204## Phase 1.75: Document-Set Analysis
205
206After investigating individual docs, step back and evaluate the document set as a whole. The goal is to catch problems that only become visible when comparing docs to each other — not just to reality.
207
208### Overlap Detection
209
210For docs that share the same module, component, tags, or problem domain, compare them across these dimensions:
211
212- **Problem statement** — do they describe the same underlying problem?
213- **Solution shape** — do they recommend the same approach, even if worded differently?
214- **Referenced files** — do they point to the same code paths?
215- **Prevention rules** — do they repeat the same prevention bullets?
216- **Root cause** — do they identify the same root cause?
217
218High overlap across 3+ dimensions is a strong Consolidate signal. The question to ask: "Would a future maintainer need to read both docs to get the current truth, or is one mostly repeating the other?"
219
220### Supersession Signals
221
222Detect "older narrow precursor, newer canonical doc" patterns:
223
224- A newer doc covers the same files, same workflow, and broader runtime behavior than an older doc
225- An older doc describes a specific incident that a newer doc generalizes into a pattern
226- Two docs recommend the same fix but the newer one has better context, examples, or scope
227
228When a newer doc clearly subsumes an older one, the older doc is a consolidation candidate — its unique content (if any) should be merged into the newer doc, and the older doc should be deleted.
229
230### Canonical Doc Identification
231
232For each topic cluster (docs sharing a problem domain), identify which doc is the **canonical source of truth**:
233
234- Usually the most recent, broadest, most accurate doc in the cluster
235- The one a maintainer should find first when searching for this topic
236- The one that other docs should point to, not duplicate
237
238All other docs in the cluster are either:
239- **Distinct** — they cover a meaningfully different sub-problem and have independent retrieval value. Keep them separate.
240- **Subsumed** — their unique content fits as a section in the canonical doc. Consolidate.
241- **Redundant** — they add nothing the canonical doc doesn't already say. Delete.
242
243### Retrieval-Value Test
244
245Before recommending that two docs stay separate, apply this test: "If a maintainer searched for this topic six months from now, would having these as separate docs improve discoverability, or just create drift risk?"
246
247Separate docs earn their keep only when:
248- They cover genuinely different sub-problems that someone might search for independently
249- They target different audiences or contexts (e.g., one is about debugging, another about prevention)
250- Merging them would create an unwieldy doc that is harder to navigate than two focused ones
251
252If none of these apply, prefer consolidation. Two docs covering the same ground will eventually drift apart and contradict each other — that is worse than a slightly longer single doc.
253
254### Cross-Doc Conflict Check
255
256Look for outright contradictions between docs in scope:
257- Doc A says "always use approach X" while Doc B says "avoid approach X"
258- Doc A references a file path that Doc B says was deprecated
259- Doc A and Doc B describe different root causes for what appears to be the same problem
260
261Contradictions between docs are more urgent than individual staleness — they actively confuse readers. Flag these for immediate resolution, either through Consolidate (if one is right and the other is a stale version of the same truth) or through targeted Update/Replace.
262
263## Subagent Strategy
264
265Use subagents for context isolation when investigating multiple artifacts — not just because the task sounds complex. Choose the lightest approach that fits:
266
267| Approach | When to use |
268|----------|-------------|
269| **Main thread only** | Small scope, short docs |
270| **Sequential subagents** | 1-2 artifacts with many supporting files to read |
271| **Parallel subagents** | 3+ truly independent artifacts with low overlap |
272| **Batched subagents** | Broad sweeps — narrow scope first, then investigate in batches |
273
274**When spawning any subagent, include this instruction in its task prompt:**
275
276> Use dedicated file search and read tools (Glob, Grep, Read) for all investigation. Do NOT use shell commands (ls, find, cat, grep, test, bash) for file operations. This avoids permission prompts and is more reliable.
277>
278> Also read MEMORY.md from the auto memory directory if it exists. Check for notes related to the learning's problem domain. Report any memory-sourced drift signals separately from codebase-sourced evidence, tagged with "(auto memory [claude])" in the evidence section. If MEMORY.md does not exist or is empty, skip this check.
279
280There are two subagent roles:
281
2821. **Investigation subagents** — read-only. They must not edit files, create successors, or delete anything. Each returns: file path, evidence, recommended action, confidence, and open questions. These can run in parallel when artifacts are independent.
2832. **Replacement subagents** — write a single new learning to replace a stale one. These run **one at a time, sequentially** (each replacement subagent may need to read significant code, and running multiple in parallel risks context exhaustion). The orchestrator handles all deletions and metadata updates after each replacement completes.
284
285The orchestrator merges investigation results, detects contradictions, coordinates replacement subagents, and performs all deletions/metadata edits centrally. In interactive mode, it asks the user questions on ambiguous cases. In autofix mode, it marks ambiguous cases as stale instead. If two artifacts overlap or discuss the same root issue, investigate them together rather than parallelizing.
286
287## Phase 2: Classify the Right Maintenance Action
288
289After gathering evidence, assign one recommended action.
290
291### Keep
292
293The learning is still accurate and useful. Do not edit the file — report that it was reviewed and remains trustworthy. Only add last_refreshed if you are already making a meaningful update for another reason.
294
295### Update
296
297The core solution is still valid but references have drifted (paths, class names, links, code snippets, metadata). Apply the fixes directly.
298
299### Consolidate
300
301Choose **Consolidate** when Phase 1.75 identified docs that overlap heavily but are both materially correct. This is different from Update (which fixes drift in a single doc) and Replace (which rewrites misleading guidance). Consolidate handles the "both right, one subsumes the other" case.
302
303**When to consolidate:**
304
305- Two docs describe the same problem and recommend the same (or compatible) solution
306- One doc is a narrow precursor and a newer doc covers the same ground more broadly
307- The unique content from the subsumed doc can fit as a section or addendum in the canonical doc
308- Keeping both creates drift risk without meaningful retrieval benefit
309
310**When NOT to consolidate** (apply the Retrieval-Value Test from Phase 1.75):
311
312- The docs cover genuinely different sub-problems that someone would search for independently
313- Merging would create an unwieldy doc that harms navigation more than drift risk harms accuracy
314
315**Consolidate vs Delete:** If the subsumed doc has unique content worth preserving (edge cases, alternative approaches, extra prevention rules), use Consolidate to merge that content first. If the subsumed doc adds nothing the canonical doc doesn't already say, skip straight to Delete.
316
317The Consolidate action is: merge unique content from the subsumed doc into the canonical doc, then delete the subsumed doc. Not archive — delete. Git history preserves it.
318
319### Replace
320
321Choose **Replace** when the learning's core guidance is now misleading — the recommended fix changed materially, the root cause or architecture shifted, or the preferred pattern is different.
322
323The user may have invoked the refresh months after the original learning was written. Do not ask them for replacement context they are unlikely to have — use agent intelligence to investigate the codebase and synthesize the replacement.
324
325**Evidence assessment:**
326
327By the time you identify a Replace candidate, Phase 1 investigation has already gathered significant evidence: the old learning's claims, what the current code actually does, and where the drift occurred. Assess whether this evidence is sufficient to write a trustworthy replacement:
328
329- **Sufficient evidence** — you understand both what the old learning recommended AND what the current approach is. The investigation found the current code patterns, the new file locations, the changed architecture. → Proceed to write the replacement (see Phase 4 Replace Flow).
330- **Insufficient evidence** — the drift is so fundamental that you cannot confidently document the current approach. The entire subsystem was replaced, or the new architecture is too complex to understand from a file scan alone. → Mark as stale in place:
331 - Add status: stale, stale_reason: [what you found], stale_date: YYYY-MM-DD to the frontmatter
332 - Report what evidence you found and what is missing
333 - Recommend the user run ce:compound after their next encounter with that area, when they have fresh problem-solving context
334
335### Delete
336
337Choose **Delete** when:
338
339- The code or workflow no longer exists and the problem domain is gone
340- The learning is obsolete and has no modern replacement worth documenting
341- The learning is fully redundant with another doc (use Consolidate if there is unique content to merge first)
342- There is no meaningful successor evidence suggesting it should be replaced instead
343
344Action: delete the file. No archival directory, no metadata — just delete it. Git history preserves every deleted file if recovery is ever needed.
345
346### Before deleting: check if the problem domain is still active
347
348When a learning's referenced files are gone, that is strong evidence — but only that the **implementation** is gone. Before deleting, reason about whether the **problem the learning solves** is still a concern in the codebase:
349
350- A learning about session token storage where auth_token.rb is gone — does the application still handle session tokens? If so, the concept persists under a new implementation. That is Replace, not Delete.
351- A learning about a deprecated API endpoint where the entire feature was removed — the problem domain is gone. That is Delete.
352
353Do not search mechanically for keywords from the old learning. Instead, understand what problem the learning addresses, then investigate whether that problem domain still exists in the codebase. The agent understands concepts — use that understanding to look for where the problem lives now, not where the old code used to be.
354
355**Auto-delete only when both the implementation AND the problem domain are gone:**
356
357- the referenced code is gone AND the application no longer deals with that problem domain
358- the learning is fully superseded by a clearly better successor AND the old doc adds no distinct value
359- the document is plainly redundant and adds nothing the canonical doc doesn't already say
360
361If the implementation is gone but the problem domain persists (the app still does auth, still processes payments, still handles migrations), classify as **Replace** — the problem still matters and the current approach should be documented.
362
363Do not keep a learning just because its general advice is "still sound" — if the specific code it references is gone, the learning misleads readers. But do not delete a learning whose problem domain is still active — that knowledge gap should be filled with a replacement.
364
365## Pattern Guidance
366
367Apply the same five outcomes (Keep, Update, Consolidate, Replace, Delete) to pattern docs, but evaluate them as **derived guidance** rather than incident-level learnings. Key differences:
368
369- **Keep**: the underlying learnings still support the generalized rule and examples remain representative
370- **Update**: the rule holds but examples, links, scope, or supporting references drifted
371- **Consolidate**: two pattern docs generalize the same set of learnings or cover the same design concern — merge into one canonical pattern
372- **Replace**: the generalized rule is now misleading, or the underlying learnings support a different synthesis. Base the replacement on the refreshed learning set — do not invent new rules from guesswork
373- **Delete**: the pattern is no longer valid, no longer recurring, or fully subsumed by a stronger pattern doc with no unique content remaining
374
375## Phase 3: Ask for Decisions
376
377### Autofix mode
378
379**Skip this entire phase. Do not ask any questions. Do not present options. Do not wait for input.** Proceed directly to Phase 4 and execute all actions based on the classifications from Phase 2:
380
381- Unambiguous Keep, Update, Consolidate, auto-Delete, and Replace (with sufficient evidence) → execute directly
382- Ambiguous cases → mark as stale
383- Then generate the report (see Output Format)
384
385### Interactive mode
386
387Most Updates and Consolidations should be applied directly without asking. Only ask the user when:
388
389- The right action is genuinely ambiguous (Update vs Replace vs Consolidate vs Delete)
390- You are about to Delete a document **and** the evidence is not unambiguous (see auto-delete criteria in Phase 2). When auto-delete criteria are met, proceed without asking.
391- You are about to Consolidate and the choice of canonical doc is not clear-cut
392- You are about to create a successor via Replace
393
394Do **not** ask questions about whether code changes were intentional, whether the user wants to fix bugs in the code, or other concerns outside doc maintenance. Stay in your lane — doc accuracy.
395
396#### Question Style
397
398Always present choices using the platform's blocking question tool when available (AskUserQuestion in Claude Code, request_user_input in Codex, ask_user in Gemini). Otherwise, present numbered options in plain text and wait for the user's reply before proceeding.
399
400Question rules:
401
402- Ask **one question at a time**
403- Prefer **multiple choice**
404- Lead with the **recommended option**
405- Explain the rationale for the recommendation in one concise sentence
406- Avoid asking the user to choose from actions that are not actually plausible
407
408#### Focused Scope
409
410For a single artifact, present:
411
412- file path
413- 2-4 bullets of evidence
414- recommended action
415
416Then ask:
417
418```text
419This [learning/pattern] looks like a [Keep/Update/Consolidate/Replace/Delete].
420
421Why: [one-sentence rationale based on the evidence]
422
423What would you like to do?
424
4251. [Recommended action]
4262. [Second plausible action]
4273. Skip for now
428```
429
430Do not list all five actions unless all five are genuinely plausible.
431
432#### Batch Scope
433
434For several learnings:
435
4361. Group obvious **Keep** cases together
4372. Group obvious **Update** cases together when the fixes are straightforward
4383. Present **Consolidate** cases together when the canonical doc is clear
4394. Present **Replace** cases individually or in very small groups
4405. Present **Delete** cases individually unless they are strong auto-delete candidates
441
442Ask for confirmation in stages:
443
4441. Confirm grouped Keep/Update recommendations
4452. Then handle Consolidate groups (present the canonical doc and what gets merged)
4463. Then handle Replace one at a time
4474. Then handle Delete one at a time unless the deletion is unambiguous and safe to auto-apply
448
449#### Broad Scope
450
451If the user asked for a sweeping refresh, keep the interaction incremental:
452
4531. Narrow scope first
4542. Investigate a manageable batch
4553. Present recommendations
4564. Ask whether to continue to the next batch
457
458Do not front-load the user with a full maintenance queue.
459
460## Phase 4: Execute the Chosen Action
461
462### Keep Flow
463
464No file edit by default. Summarize why the learning remains trustworthy.
465
466### Update Flow
467
468Apply in-place edits only when the solution is still substantively correct.
469
470Examples of valid in-place updates:
471
472- Rename app/models/auth_token.rb reference to app/models/session_token.rb
473- Update module: AuthToken to module: SessionToken
474- Fix outdated links to related docs
475- Refresh implementation notes after a directory move
476
477Examples that should **not** be in-place updates:
478
479- Fixing a typo with no effect on understanding
480- Rewording prose for style alone
481- Small cleanup that does not materially improve accuracy or usability
482- The old fix is now an anti-pattern
483- The system architecture changed enough that the old guidance is misleading
484- The troubleshooting path is materially different
485
486Those cases require **Replace**, not Update.
487
488### Consolidate Flow
489
490The orchestrator handles consolidation directly (no subagent needed — the docs are already read and the merge is a focused edit). Process Consolidate candidates by topic cluster. For each cluster identified in Phase 1.75:
491
4921. **Confirm the canonical doc** — the broader, more current, more accurate doc in the cluster.
4932. **Extract unique content** from the subsumed doc(s) — anything the canonical doc does not already cover. This might be specific edge cases, additional prevention rules, or alternative debugging approaches.
4943. **Merge unique content** into the canonical doc in a natural location. Do not just append — integrate it where it logically belongs. If the unique content is small (a bullet point, a sentence), inline it. If it is a substantial sub-topic, add it as a clearly labeled section.
4954. **Update cross-references** — if any other docs reference the subsumed doc, update those references to point to the canonical doc.
4965. **Delete the subsumed doc.** Do not archive it, do not add redirect metadata — just delete the file. Git history preserves it.
497
498If a doc cluster has 3+ overlapping docs, process pairwise: consolidate the two most overlapping docs first, then evaluate whether the merged result should be consolidated with the next doc.
499
500**Structural edits beyond merge:** Consolidate also covers the reverse case. If one doc has grown unwieldy and covers multiple distinct problems that would benefit from separate retrieval, it is valid to recommend splitting it. Only do this when the sub-topics are genuinely independent and a maintainer might search for one without needing the other.
501
502### Replace Flow
503
504Process Replace candidates **one at a time, sequentially**. Each replacement is written by a subagent to protect the main context window.
505
506When a replacement is needed, read the documentation contract files and pass their contents into the replacement subagent's task prompt:
507
508- references/schema.yaml — frontmatter fields and enum values
509- references/yaml-schema.md — category mapping
510- assets/resolution-template.md — section structure
511
512Do not let replacement subagents invent frontmatter fields, enum values, or section order from memory.
513
514**When evidence is sufficient:**
515
5161. Spawn a single subagent to write the replacement learning. Pass it:
517 - The old learning's full content
518 - A summary of the investigation evidence (what changed, what the current code does, why the old guidance is misleading)
519 - The target path and category (same category as the old learning unless the category itself changed)
520 - The relevant contents of the three support files listed above
5212. The subagent writes the new learning using the support files as the source of truth: references/schema.yaml for frontmatter fields and enum values, references/yaml-schema.md for category mapping, and assets/resolution-template.md for section order. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
5223. After the subagent completes, the orchestrator deletes the old learning file. The new learning's frontmatter may include supersedes: [old learning filename] for traceability, but this is optional — the git history and commit message provide the same information.
523
524**When evidence is insufficient:**
525
5261. Mark the learning as stale in place:
527 - Add to frontmatter: status: stale, stale_reason: [what you found], stale_date: YYYY-MM-DD
5282. Report what evidence was found and what is missing
5293. Recommend the user run ce:compound after their next encounter with that area
530
531### Delete Flow
532
533Delete only when a learning is clearly obsolete, redundant (with no unique content to merge), or its problem domain is gone. Do not delete a document just because it is old — age alone is not a signal.
534
535## Output Format
536
537**The full report MUST be printed as markdown output.** Do not summarize findings internally and then output a one-liner. The report is the deliverable — print every section in full, formatted as readable markdown with headers, tables, and bullet points.
538
539After processing the selected scope, output the following report:
540
541```text
542Compound Refresh Summary
543========================
544Scanned: N learnings
545
546Kept: X
547Updated: Y
548Consolidated: C
549Replaced: Z
550Deleted: W
551Skipped: V
552Marked stale: S
553```
554
555Then for EVERY file processed, list:
556- The file path
557- The classification (Keep/Update/Consolidate/Replace/Delete/Stale)
558- What evidence was found -- tag any memory-sourced findings with "(auto memory [claude])" to distinguish them from codebase-sourced evidence
559- What action was taken (or recommended)
560- For Consolidate: which doc was canonical, what unique content was merged, what was deleted
561
562For **Keep** outcomes, list them under a reviewed-without-edits section so the result is visible without creating git churn.
563
564### Autofix mode report
565
566In autofix mode, the report is the sole deliverable — there is no user present to ask follow-up questions, so the report must be self-contained and complete. **Print the full report. Do not abbreviate, summarize, or skip sections.**
567
568Split actions into two sections:
569
570**Applied** (writes that succeeded):
571- For each **Updated** file: the file path, what references were fixed, and why
572- For each **Consolidated** cluster: the canonical doc, what unique content was merged from each subsumed doc, and the subsumed docs that were deleted
573- For each **Replaced** file: what the old learning recommended vs what the current code does, and the path to the new successor
574- For each **Deleted** file: the file path and why it was removed (problem domain gone, fully redundant, etc.)
575- For each **Marked stale** file: the file path, what evidence was found, and why it was ambiguous
576
577**Recommended** (actions that could not be written — e.g., permission denied):
578- Same detail as above, but framed as recommendations for a human to apply
579- Include enough context that the user can apply the change manually or re-run the skill interactively
580
581If all writes succeed, the Recommended section is empty. If no writes succeed (e.g., read-only invocation), all actions appear under Recommended — the report becomes a maintenance plan.
582
583**Legacy cleanup** (if docs/solutions/_archived/ exists):
584- List archived files found and recommend disposition: restore (if still relevant), delete (if truly obsolete), or consolidate (if overlapping with active docs)
585
586## Phase 5: Commit Changes
587
588After all actions are executed and the report is generated, handle committing the changes. Skip this phase if no files were modified (all Keep, or all writes failed).
589
590### Detect git context
591
592Before offering options, check:
5931. Which branch is currently checked out (main/master vs feature branch)
5942. Whether the working tree has other uncommitted changes beyond what compound-refresh modified
5953. Recent commit messages to match the repo's commit style
596
597### Autofix mode
598
599Use sensible defaults — no user to ask:
600
601| Context | Default action |
602|---------|---------------|
603| On main/master | Create a branch named for what was refreshed (e.g., docs/refresh-auth-and-ci-learnings), commit, attempt to open a PR. If PR creation fails, report the branch name. |
604| On a feature branch | Commit as a separate commit on the current branch |
605| Git operations fail | Include the recommended git commands in the report and continue |
606
607Stage only the files that compound-refresh modified — not other dirty files in the working tree.
608
609### Interactive mode
610
611First, run git branch --show-current to determine the current branch. Then present the correct options based on the result. Stage only compound-refresh files regardless of which option the user picks.
612
613**If the current branch is main, master, or the repo's default branch:**
614
6151. Create a branch, commit, and open a PR (recommended) — the branch name should be specific to what was refreshed, not generic (e.g., docs/refresh-auth-learnings not docs/compound-refresh)
6162. Commit directly to {current branch name}
6173. Don't commit — I'll handle it
618
619**If the current branch is a feature branch, clean working tree:**
620
6211. Commit to {current branch name} as a separate commit (recommended)
6222. Create a separate branch and commit
6233. Don't commit
624
625**If the current branch is a feature branch, dirty working tree (other uncommitted changes):**
626
6271. Commit only the compound-refresh changes to {current branch name} (selective staging — other dirty files stay untouched)
6282. Don't commit
629
630### Commit message
631
632Write a descriptive commit message that:
633- Summarizes what was refreshed (e.g., "update 3 stale learnings, consolidate 2 overlapping docs, delete 1 obsolete doc")
634- Follows the repo's existing commit conventions (check recent git log for style)
635- Is succinct — the details are in the changed files themselves
636
637## Relationship to ce:compound
638
639- ce:compound captures a newly solved, verified problem
640- ce:compound-refresh maintains older learnings as the codebase evolves — both their individual accuracy and their collective design as a document set
641
642Use **Replace** only when the refresh process has enough real evidence to write a trustworthy successor. When evidence is insufficient, mark as stale and recommend ce:compound for when the user next encounters that problem area.
643
644Use **Consolidate** proactively when the document set has grown organically and redundancy has crept in. Every ce:compound invocation adds a new doc — over time, multiple docs may cover the same problem from slightly different angles. Periodic consolidation keeps the document set lean and authoritative.
645
In the file
SKILL.md6,594 words
Files4
LicenceMIT
Why you can read it

Nothing in a skill executes. The client loads the text and the model follows it, so a skill can be audited the way a runbook is — by reading it.

What it costs in context

Skills are not billed by the call. They are paid for in context: every token the instructions occupy is a token your code, your diff and your conversation cannot use. Here is what this one takes and when it takes it.

≈170
always loaded
The name and description, so the model knows the skill exists and when to reach for it.
12,180
on trigger
The instruction body and 3 supporting files, read only when the skill fires.
6.2%
of a 200k window
Ten skills this size would take about 62% of the window before you open a file.
050k100k150k200k context window

12.3k tokens, estimated from the bundle at four bytes to the token, held for the rest of the session once it triggers. Heavy. Teams tend to install this one per project rather than globally, and load it only when the job comes up.

Servers bill, skills cost

A server charges by the month. A skill charges once per session, in context, and then keeps charging it for as long as the session lives.

Before and after

The same question, put to the same model twice: once as it comes, and once with these instructions loaded.

No worked example has been published for this skill yet.

Adoption
Installsnone yet
Ratingno reviews yet

The procedure it runs

The procedure has not been published here. It is in the skill’s own SKILL.md, which its author has not sent to the marketplace yet.

Prose, not code

These steps are written for a model to follow, not executed by a runtime. It can still be told to skip one, and it will say so when it does.

Servers it uses

None. This skill calls no MCP servers at all.

Everything it needs is in the instructions, so it works in a project with nothing connected — the model reads the file and changes how it works with what it can already reach.

It writes no files and reaches no network. All it changes is how the model reasons and writes.

What it asks for
Writes filesno
Network accessno

Read from the allowed-tools line of this skill’s own SKILL.md. A skill grants no permissions of its own — it can only ask for tools your client already has.

What it will not do

Every skill is narrow, and the useful ones say where they stop. These are the jobs this one is the wrong tool for.

What this skill is not for has not been published here. Nothing is implied by that: it is a section the author has not filled in.

What is in the bundle

4 files, 49.4 kB on disk. A bundle is text throughout: the instructions the model reads, plus the templates it fills in.

  • SKILL.md42.8 kB
  • assets/resolution-template.md0.8 kB
  • references/schema.yaml3.0 kB
  • references/yaml-schema.md2.8 kB
What is not in it

No dependencies and nothing executable: a skill is text the agent reads, so the bundle is 4 files you can review in full before installing. The MIT licence covers the templates and examples as well as the instructions.

Install

Installing copies the bundle into your project. Nothing runs at install time — the files sit on disk until the model reads them.

# Compound Refresh · 12.3k tokens when loaded npx mcprush@latest skill add everyinc/compound-refresh

Writes to .claude/skills/compound-refresh/ in the current project. Add --global to put it in your home directory instead, for every project.

Which clients pick it up on their own

A skill is a folder of text. A client with a skills folder reads it without being told; everywhere else the same text works, it is just handed to the model rather than found.

Claude Code.claude/skills/
Claude Desktop
ChatGPT
Cursor.cursor/skills/
VS Code.github/skills/
Codex CLI.agents/skills/
Gemini CLI.gemini/skills/
Grok.grok/skills/
Zed.agents/skills/
Windsurf.windsurf/skills/
Agent SDK.claude/skills/
HTTP / API
This release
Versionnot versioned
Publishedno release date on file
PriceFree
Referenceeveryinc/compound-refresh

Versions

Its author publishes no version number, so there is nothing here to pin to: what you install is the folder as it stands today. Instructions change more often than APIs do — a skill can be rewritten entirely without anything it depends on moving.

v
  • No earlier releases have been published to the marketplace.
Pinning

Nothing to pin to: this skill carries no version number of its own. What you install is what the folder holds on the day you install it.

Reviews

—no reviews yet · no installs yet

Nobody has reviewed this skill yet. The rating is the mean of the reviews written here, so there is none until somebody writes the first.

Who can post

Only accounts that have had the skill installed for fourteen days, so a review is written after living with it rather than after reading it. Publishers may reply once.

Who wrote it

EV
EveryInc

Publishes on mcprush.

0 servers listed4 skills listednot claimed
Profile
Publisher
Servers0
Claim this skill