Compound Refresh — Learning Docs Maintenance
Automatically audit and maintain solution docs in your repo, clearing stale entries to keep your knowledge base trustworthy.
The skill includes an inline bash script that executes a context script, which interprets agent tool usage and may override system prompt restrictions. It also instructs agents to silently perform file writes, deletions, renames, and merges in non-interactive mode without user confirmation. While error scenarios are handled with graceful degradation, the lack of explicit user confirmation steps and unclear trust in internal scripts lowers the trust score. Scored 12 as main risks are visible but permission control, confirmation, isolation, and recovery are incomplete.
The skill uses a structured workflow with context and validation scripts, including error handling and graceful degradation (e.g., continue if script missing or fails). However, static review cannot verify script reliability in real environments, and no complete test suite is present. Scored 9 because key paths have guards but lack real validation; failure feedback is adequate but coverage is thin.
The skill defines clear use cases, scope hints, and non-interactive mode, with scope-narrowing strategies and explicit boundaries (e.g., not processing unspecified scopes). However, trigger conditions may be overly specific, risking false triggers or missed invocations. Environmental fit lacks explicit mention of China network reachability. Scored 10 because scenarios are clear but boundary evidence is limited.
The skill is well-structured with detailed reference files and scripts, including schema, yaml validation, and claims validation. It includes an MIT license, clear maintenance path, and version control. But changelog and version numbers are absent, and reliance on unverified external scripts reduces score. Scored 11 because documentation layering is clear with sufficient examples, but versioning and governance are incomplete.
The skill has clear objectives to audit and refresh learning docs, with detailed operation flows. But static review cannot verify actual effectiveness, and the output format (report) requires interpretation, limiting direct usability. Scored 6 because core task is clearly described but actual outputs are unverified and marginal value evidence is limited.
Static review cannot execute scripts or verify their authenticity. Although validation scripts are provided (e.g., validate-frontmatter.py and validate-doc-claims.py), there is no independent test suite or third-party execution evidence. Scored 4 because auditable primary material is limited and independent verification is not possible.
- The skill automatically performs writes, deletions, renames, and merges in non-interactive mode; ensure your environment is backed up to prevent accidental data loss.
- The context.mjs script may alter agent tool authorization; use it in a trusted environment and review its output.
- The skill claims multi-platform support but does not verify availability in mainland China networks; external services may be unreachable.
What does this skill do, and when should you use it?
This skill audits Markdown learning docs under <root>/solutions/, cross-references them against the current codebase, and applies maintenance actions: keeping valid docs, updating drifted references, consolidating overlapping ones, replacing misleading guidance, or deleting obsolete entries. It produces a comprehensive report and commits changes, asking for user input when needed. The skill supports both interactive and non-interactive modes, handles broad sweeps of 9+ docs, and includes vocabulary reconciliation with CONCEPTS.md and a discoverability check.
Scans Markdown files under <root>/solutions/ (excluding READMEs), validates claims against code, classifies each doc as Keep/Update/Consolidate/Replace/Delete, runs a setup script for context, dispatches subagents for investigation, rewrites docs during Replace, updates citations, reconciles CONCEPTS.md, emits a detailed report, and creates Git commits (interactive asks first).
- Developers want to ensure past solution notes still match the latest code after a feature adds complexity.
- Teams need to batch-update docs when class paths or module names change in refactors.
- Maintainers want to merge two largely overlapping solutions into one canonical doc.
- CI pipelines run non-interactively to tidy stale learnings without human intervention.
- Users suspect a doc's recommended solution is outdated and need evidence to decide between update and replace.
What are this skill's strengths and limitations?
- Automates knowledge-base maintenance, saving manual effort.
- Provides clear action classifications (keep, update, consolidate, replace, delete) reducing subjectivity.
- Supports non-interactive mode for CI integration.
- Ensures docs stay in sync with code, preventing stale information.
- Requires codebase access for verification.
- May keep unverifiable claims, missing some drift.
- Complex actions (replace, split) need human confirmation.
- Test coverage or cross-platform specifics are not explicitly stated.
How do you install this skill?
Install as part of the official Compound Engineering plugin via plugin systems. For Claude Code: /plugin marketplace add EveryInc/compound-engineering-plugin then /plugin install compound-engineering. Cursor uses /add-plugin compound-engineering, Codex CLI uses codex plugin marketplace add and codex plugin add.
How do you use this skill?
Invoke the skill from a supported coding agent by natural language, e.g., 'run ce-compound-refresh', optionally with a scope hint like 'ce-compound-refresh src/module'. Add mode:non-interactive for unattended runs. The skill reads config, scans docs, executes maintenance, and outputs a report.