compound-refresh

name	compound-refresh
description	Review and maintain institutional learnings in docs/compound/ so the compound library stays accurate, deduplicated, and evidence-backed

Compound Refresh

Review the existing compound library in docs/compound/ and keep it aligned with current code, architecture, and workflow reality. Use this skill to maintain existing learnings; use compound to capture a brand-new solved problem.

When to Use

Invoke when:

• shipped work supersedes, contradicts, or duplicates existing compound entries
• tuning detects compound artifacts that drift from current code reality
• the compound library has overlapping, stale, or low-signal entries

Inputs

• scope: (Optional, default recent) One of recent, all, or a subdirectory / glob under docs/compound/.
• context: (Optional) Feature, chore, PR, release, or tuning context explaining why the refresh is being performed.
• mode: (Optional, default propose) One of propose or apply.

Output

• Refresh report at docs/closure/{YYYY-MM-DD}-{slug}-compound-refresh.md
• Updated or marked-stale compound files in docs/compound/ when mode=apply
• Explicit classifications for reviewed entries: keep / update / consolidate / replace / delete

Required Protocol

Phase 1: Gather Evidence

1. Determine which compound entries are in scope from:
   • changed files, APIs, or runtime surfaces
   • recent closure artifacts, plans, or memory checkpoints
   • citations already present in compound entries
   • overlapping tags, categories, or root-cause patterns
2. Read the relevant entries plus the current code or docs that confirm whether they are still accurate.
3. Prefer evidence from shipped code, verified behavior, or durable design docs over intuition.

Phase 2: Classify Each Entry

Assign one outcome per reviewed entry:

• keep — still accurate, distinct, and worth keeping as-is
• update — still valuable, but details or citations drifted
• consolidate — overlaps materially with one or more other entries and should become a single stronger learning
• replace — the entry's core guidance is obsolete and should be superseded by a better version with preserved citations
• delete — duplicate, misleading, or no longer worth keeping after its useful signal has been absorbed elsewhere

If confidence is low, do not guess. Mark the entry as stale in the report or in frontmatter rather than rewriting it blindly.

Phase 3: Apply Evidence-Backed Maintenance

When mode=apply:

1. Update entries in place only when the new wording is supported by current evidence and preserves useful citations.
2. Consolidate overlapping entries into a stronger single document and retain traceability to the originals.
3. Replace obsolete guidance with a new entry that cites the superseded file and the newer evidence.
4. For delete, prefer archiving or clearly marking the entry stale unless the workspace's normal workflow already allows safe removal of obsolete docs.

When mode=propose, do not edit files. Emit the recommended action and the evidence that justifies it.

Phase 4: Write the Refresh Report

Record:

• entries reviewed
• their classifications
• evidence used
• files updated, consolidated, replaced, archived, or left stale
• follow-up items requiring manual review

Behavioral Constraints

• Prefer evidence-backed maintenance over cosmetic rewrites
• Preserve or improve citations whenever an entry changes
• Do not remove the only useful learning for a recurring problem without a stronger replacement or archival trail
• When uncertain, mark stale or recommend manual review instead of inventing certainty

Model Routing

This skill operates at Tier 1 (Fast/Cheap) unless the compound library is large or the refresh requires cross-cutting architecture judgment.

Generated by autoharness | Template: compound-refresh/SKILL.md.tmpl