Compound Refresh

Maintain 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.

Mode Detection

Check if $ARGUMENTS contains mode:autofix. If present, strip it from arguments (use the remainder as a scope hint) and run in autofix mode.

Autofix mode rules

• Skip all user questions. Never pause for input.
• Process all docs in scope. No scope narrowing questions — if no scope hint was provided, process everything.
• 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.
• 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.
• 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.
• 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.

Interaction Principles

These principles apply to interactive mode only. In autofix mode, skip all user questions and apply the autofix mode rules above.

Follow the same interaction style as ce-brainstorm:

• Ask questions one at a time — use the platform's blocking question tool: AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), request_user_input in Codex, ask_user in Gemini, ask_user in Pi (requires the pi-ask-user extension). Fall back to numbered options in plain text only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question
• Prefer multiple choice when natural options exist
• Start with scope and intent, then narrow only when needed
• Do not ask the user to make decisions before you have evidence
• Lead with a recommendation and explain it briefly

The 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.

Refresh Order

Refresh in this order:

1. Review the relevant individual learning docs first
2. Note which learnings stayed valid, were updated, were consolidated, were replaced, or were deleted
3. Then review any pattern docs that depend on those learnings

Why this order:

• learning docs are the primary evidence
• pattern docs are derived from one or more learnings
• stale learnings can make a pattern look more valid than it really is

If 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.

Maintenance Model

For each candidate artifact, classify it into one of five outcomes:

Core Rules

1. Evidence informs judgment. The signals below are inputs, not a mechanical scorecard. Use engineering judgment to decide whether the artifact is still trustworthy.
2. Prefer no-write Keep. Do not update a doc just to leave a review breadcrumb.
3. 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.
4. 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.
5. 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.
6. 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.
7. Use Replace only when there is a real replacement. That means either:
   • the current conversation contains a recently solved, verified replacement fix, or
   • the user has provided enough concrete replacement context to document the successor honestly, or
   • the codebase investigation found the current approach and can document it as the successor, or
   • newer docs, pattern docs, PRs, or issues provide strong successor evidence.
8. 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.
9. 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.
10. 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.

Scope Selection

Start by discovering learnings and pattern docs under docs/solutions/.

Exclude:

• README.md
• docs/solutions/_archived/ (legacy — if this directory exists, flag it for cleanup in the report)

Find 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).

If $ARGUMENTS is provided, use it to narrow scope before proceeding. Try these matching strategies in order, stopping at the first that produces results:

1. Directory match — check if the argument matches a subdirectory name under docs/solutions/ (e.g., performance-issues, database-issues)
2. Frontmatter match — search module, component, or tags fields in learning frontmatter for the argument
3. Filename match — match against filenames (partial matches are fine)
4. Content search — search file contents for the argument as a keyword (useful for feature names or feature areas)

If 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.

If no candidate docs are found, report:

No candidate docs found in docs/solutions/.
Run `ce-compound` after solving problems to start building your knowledge base.

Phase 0: Assess and Route

Before asking the user to classify anything:

1. Discover candidate artifacts
2. Estimate scope
3. Choose the lightest interaction path that fits

Route by Scope

Broad Scope Triage

When scope is broad (9+ candidate docs), do a lightweight triage before deep investigation:

1. Inventory — read frontmatter of all candidate docs, group by module/component/category
2. 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.
3. 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.
4. 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.

Example:

Found 24 learnings across 5 areas.

The auth module has 5 learnings and 2 pattern docs that cross-reference
each other — and 3 of those reference files that no longer exist.
I'd start there.

1. Start with auth (recommended)
2. Pick a different area
3. Review everything

Do not ask action-selection questions yet. First gather evidence.

Phase 1: Investigate Candidate Learnings

For each learning in scope, read it, cross-reference its claims against the current codebase, and form a recommendation.

A learning has several dimensions that can independently go stale. Surface-level checks catch the obvious drift, but staleness often hides deeper:

• References — do the file paths, class names, and modules it mentions still exist or have they moved?
• 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.
• Code examples — if the learning includes code snippets, do they still reflect the current implementation?
• Related docs — are cross-referenced learnings and patterns still present and consistent?
• Auto memory (Claude Code only) — does the injected auto-memory block in your system prompt contain entries in the same problem domain? Scan that block directly. If the block is absent, skip this dimension. A memory note describing a different approach than what the learning recommends is a supplementary drift signal.
• 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).

Match 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.

Drift Classification: Update vs Replace

The critical distinction is whether the drift is cosmetic (references moved but the solution is the same) or substantive (the solution itself changed):

• 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.
• 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 ga