القائمة
Refresh the repo's captured learnings against the current codebase. Use when auditing stale, overlapping, superseded, or drifted learnings; avoid general refactor, debugging, or code review unless the learnings store is explicit.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | ce-compound-refresh |
| description | Refresh the repo's captured learnings against the current codebase. Use when auditing stale, overlapping, superseded, or drifted learnings; avoid general refactor, debugging, or code review unless the learnings store is explicit. |
| argument-hint | [optional: scope hint — directory, filename, module, or keyword] [mode:headless] |
Maintain the quality of <root>/solutions/ over time. This workflow reviews existing learnings against the current codebase, then refreshes any derived pattern docs that depend on them.
Check whether the arguments you were invoked with contain mode:headless. If present, strip it from the arguments (use the remainder as a scope hint) and run in headless mode.
| Mode | When | Behavior |
|---|---|---|
| Interactive (default) | User is present and can answer questions | Ask for decisions on ambiguous cases, confirm actions |
| Headless | mode:headless 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. |
status: stale, stale_reason, and stale_date in the frontmatter. If even the stale-marking write fails, include it as a recommendation.If invoked specifically to create or bootstrap CONCEPTS.md (e.g., "create a CONCEPTS.md", "build the concept map", "set up shared vocabulary"), the intent is ambiguous between two jobs — building the vocabulary file and running a /solutions refresh — so disambiguate before proceeding. 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_question in Antigravity CLI (agy), ask_user in Pi (requires the pi-ask-user extension). Fall back to numbered options in chat 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. Two options:
references/concepts-vocabulary.md and follow its Seed goal and Scope of a seed (repo-wide) rules: seed the project's core domain nouns from the declared domain model (schema, core types, primary models, top-level domain docs), each meeting the qualifying bar, the codebase setting the count. Write the preamble (see Phase 4.5), cluster per the organization rules, and run the Discoverability Check so AGENTS.md/CLAUDE.md surface the new file. Then enter Phase 5 (Commit Changes) to commit/PR the new CONCEPTS.md and any instruction-file edit through the same durable-write flow the refresh uses — do not leave the bootstrap uncommitted.CONCEPTS.md is seeded (if absent) and reconciled as part of Phase 4.5.In headless mode there is no user to ask: default to the refresh cycle (vocabulary is seeded and reconciled within Phase 4.5 regardless) and note in the report that a standalone repo-wide bootstrap was not run.
These principles apply to interactive mode only. In headless mode, skip all user questions and apply the headless mode rules above.
Follow the same interaction style as ce-brainstorm:
AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), request_user_input in Codex, ask_question in Antigravity CLI (agy), 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 questionThe 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.
This skill reviews and refreshes learnings under <root>/solutions/. Resolve <root> when you first compose a <root>/solutions/ path (per the block below); pass the resolved <root>/solutions/ path to any subagent, not the config.
Resolve the CE artifact root <root> before composing any artifact path.
docs_root from <repo-root>/.compound-engineering/config.local.yaml, then config.yaml; first non-empty value wins (<repo-root> = git rev-parse --show-toplevel). Unset -> <root> is docs, exactly as before..git/. Otherwise stop with an error naming docs_root and the value -- never fall back to docs.<root> as the sole artifact location: create it if absent, compose each path as <root>/<subdir> with this skill's own subdirectory, and never also read docs.Refresh in this order:
Why this order:
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.
For each candidate artifact, classify it into one of five outcomes:
| Outcome | Meaning | Default action |
|---|---|---|
| Keep | Still accurate and still useful | No file edit by default; report that it was reviewed and remains trustworthy |
| Update | Core solution is still correct, but references drifted | Apply evidence-backed in-place edits |
| Consolidate | Two or more docs overlap heavily but are both correct | Merge unique content into the canonical doc, delete the subsumed doc |
| Replace | The old artifact is now misleading, but there is a known better replacement | Create a trustworthy successor, then delete the old artifact |
| Delete | No longer useful, applicable, or distinct | Delete the file — git history preserves it if anyone needs to recover it later |
_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 -- <root>/solutions/ will find it.Start by discovering learnings and pattern docs under <root>/solutions/.
Exclude:
README.md<root>/solutions/_archived/ (legacy — if this directory exists, flag it for cleanup in the report)Find all .md files under <root>/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 a scope argument was provided, use it to narrow scope before proceeding. Try these matching strategies in order, stopping at the first that produces results:
<root>/solutions/ (e.g., performance-issues, database-issues)module, component, or tags fields in learning frontmatter for the argumentIf no matches are found, report that and ask the user to clarify. In headless mode, when a scope hint was provided but matched nothing, report the miss in the summary and exit without widening to all docs — do not silently fall back to processing everything. (The "process everything" rule from Headless mode rules applies only when no scope hint was provided.)
If no candidate docs are found, report:
No candidate docs found in <root>/solutions/.
Run `ce-compound` after solving problems to start building your knowledge base.
Before asking the user to classify anything:
| Scope | When to use it | Interaction style |
|---|---|---|
| Focused | 1-2 likely files or user named a specific doc | Investigate directly, then present a recommendation |
| Batch | Up to ~8 mostly independent docs | Investigate first, then present grouped recommendations |
| Broad | 9+ docs, ambiguous, or repo-wide stale-doc sweep | Triage first, then investigate in batches |
When scope is broad (9+ candidate docs), do a lightweight triage before deep investigation:
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.
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:
CONCEPTS.md? If yes, does the definition still match how the code uses the term? If no, flag the term for Phase 4.5 to add or bootstrap. Do not edit CONCEPTS.md during investigation — just collect the signal centrally.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.
The critical distinction is whether the drift is cosmetic (references moved but the solution is the same) or substantive (the solution itself changed):
ce-compound-refresh fixes these directly.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.The boundary: if you find yourself rewriting the solution section or changing what the learning recommends, stop — that is Replace, not Update.
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:
In headless mode, memory-only drift (no codebase corroboration) should result in stale-marking, not action.
Three guidelines that are easy to get wrong:
After reviewing the underlying learning docs, investigate any relevant pattern docs under <root>/solutions/patterns/.
Pattern 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.
A pattern doc with no clear supporting learnings is a stale signal — investigate carefully before keeping it unchanged.
After 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.
For docs that share the same module, component, tags, or problem domain, compare them across these dimensions:
High 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?"
Detect "older narrow precursor, newer canonical doc" patterns:
When 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.
For each topic cluster (docs sharing a problem domain), identify which doc is the canonical source of truth:
All other docs in the cluster are either:
Before 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?"
Separate docs earn their keep only when:
If 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.
Look for outright contradictions between docs in scope:
Contradictions 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.
Use subagents for context isolation when investigating multiple artifacts — not just because the task sounds complex. Choose the lightest approach that fits:
| Approach | When to use |
|---|---|
| Main thread only | Small scope, short docs |
| Sequential subagents | 1-2 artifacts with many supporting files to read |
| Parallel subagents | 3+ truly independent artifacts with low overlap |
| Batched subagents | Broad sweeps — narrow scope first, then investigate in batches |
When spawning any subagent, omit the mode parameter so the user's configured permission settings apply. Include this instruction in its task prompt:
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.
Also scan the "user's auto-memory" block injected into your system prompt (Claude Code only). 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 the block is not present in your context, skip this check.
There are two subagent roles:
The 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 headless mode, it marks ambiguous cases as stale instead. If two artifacts overlap or discuss the same root issue, investigate them together rather than parallelizing.
After gathering evidence, assign one recommended action.
The 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.
The core solution is still valid but references have drifted (paths, class names, links, code snippets, metadata). Apply the fixes directly.
Choose 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.
When to consolidate:
When NOT to consolidate (apply the Retrieval-Value Test from Phase 1.75):
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.
The 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.
Choose 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.
The 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.
Evidence assessment:
By 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:
status: stale, stale_reason: [what you found], stale_date: YYYY-MM-DD to the frontmatterce-compound after their next encounter with that area, when they have fresh problem-solving contextChoose Delete when:
Action: delete the file. No archival directory, no metadata — just delete it. Git history preserves every deleted file if recovery is ever needed.
When 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:
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.Do 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.
A doc that other files cite is load-bearing in a way the doc itself does not announce. Before classifying as Delete, search the repo's markdown content (other docs, plans, instruction files, READMEs) for citations of the file — not source code, where citations are rare and only appear in comments. The filename slug is usually unique enough that one query covers all citation sites.
Search efficiently:
.md); narrow to the full path only if matches are noisy.-B/-A), not whole files.Inbound links inform the classification, not the cleanup. Removing a citation is always mechanical (drop the parenthetical, the bare entry, or the deferring clause). The judgment is upstream: given these citations, is Delete still right, or is Replace closer to right?
Classify each citation by what it does in its citing context:
In headless mode, Delete + decorative cleanup is fine. Any substantive citation, or any genuine ambiguity, downgrades to stale-marking — writing a Replace successor is judgment-heavy and should not happen unattended.
Auto-delete only when all three hold:
If any condition fails, classify as Replace, Update, Consolidate, or stale-mark per the rules above. Do not delete a learning whose problem domain is still active or whose principles are cited substantively — fill the gap with a replacement instead.
Apply 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:
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:
Most Updates and Consolidations should be applied directly without asking. Only ask the user when:
Do 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.
Always present choices using 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_question in Antigravity CLI (agy), 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.
Question rules:
For a single artifact, present:
Then ask:
This [learning/pattern] looks like a [Keep/Update/Consolidate/Replace/Delete].
Why: [one-sentence rationale based on the evidence]
What would you like to do?
1. [Recommended action]
2. [Second plausible action]
3. Skip for now
Do not list all five actions unless all five are genuinely plausible.
For several learnings:
Ask for confirmation in stages:
If the user asked for a sweeping refresh, keep the interaction incremental:
Do not front-load the user with a full maintenance queue.
For each candidate, execute the flow that matches its classification from Phase 2 (confirmed in Phase 3). Read references/per-action-flows.md and follow the matching section:
Only one flow runs per candidate; the reference contains the per-action criteria, examples, and step-by-step instructions.
After the per-learning actions execute, aggregate the domain terms flagged across Phase 1's Vocabulary dimension and reconcile them with CONCEPTS.md.
First, read references/concepts-vocabulary.md. This is unconditional. Do not pre-judge from memory which Phase 1 signals qualify — the reference's criteria are non-obvious and a "nothing qualifies" judgment without reading is a shortcut, not a result.
Procedure:
Aggregate. Collect qualifying terms surfaced across the learnings in scope, applying the reference's criteria. If the same term surfaced in multiple learnings with different shades of precision, union the shades into one entry — not three entries, not most-recent-wins.
If CONCEPTS.md exists, add missing terms and refine existing entries when the corpus surfaced new precision. Do not duplicate entries already present. Then reconcile the in-scope core nouns: re-derive the core domain nouns of the area in scope from its declared model (per the Seed goal in the reference) and backfill any that are central but missing. This is the every-run safety net for stable-central terms that friction never surfaces — bounded to the area in scope, defining only terms investigated this run, never a repo-wide sweep.
If CONCEPTS.md does not exist and at least one qualifying term was surfaced, bootstrap it — and seed, don't write a single term. Alongside the surfaced term(s), seed the core domain nouns of the area in scope per the reference's Seed goal, so the file is anchored from creation rather than a lone peripheral entry (and so captured terms don't dangle against undefined siblings). The seed stays scoped to the area in scope — a repo-wide concept map comes only from the explicit bootstrap path above, not from a scoped refresh. At creation, hold the qualifying bar conservatively for borderline terms — a borderline term or a class/table/file name dressed up as an entity defers to a later run; clear core nouns are seeded, borderline ones wait. The conservatism is about quality, not count; updates to an existing file follow normal criteria.
Scope discipline and citation hygiene. Bootstrap, seed, and reconcile reflect only the area in scope — do not expand to other categories, and do not retroactively inject (see CONCEPTS.md) pointers into existing learnings. (The repo-wide bootstrap path above is the deliberate exception — it intentionally covers the whole declared model.) The report should note that additional entries are likely from refresh runs on other scopes.
Initial structure. When bootstrapping, start the file with this preamble under the # Concepts heading:
Shared domain vocabulary for this project — entities, named processes, and status concepts with project-specific meaning. Seeded with core domain vocabulary, then accretes as ce-compound and ce-compound-refresh process learnings; direct edits are fine. Glossary only, not a spec or catch-all.
Then add entries. Let term count drive shape: 1-4 terms → flat headings, more → cluster by domain relationship per the rules in references/concepts-vocabulary.md.
Scrub violations. Scan existing entries for content that violates references/concepts-vocabulary.md criteria — implementation specifics (file paths, class names, function signatures, code references), current-config values (thresholds, counts, enum values that will drift), status/owner/date metadata, duplicates of terms covered under a different name, or entries that lean on an undefined project-specific sibling (add the sibling or rephrase). Rewrite or consolidate. The full sweep is appropriate here because refresh is an audit; ce-compound's same-named phase scopes corrections to the coherence neighborhood of entries being touched.
If no Phase 1 signals qualified after applying the reference's criteria, record that outcome explicitly in the report's CONCEPTS.md line (e.g., "scanned, no qualifying terms"). Do not silently skip — the visible scan-and-no-result record is the audit signal that the reference was consulted.
Note: if this run creates CONCEPTS.md from scratch, the Discoverability Check below also surfaces it so future agents can discover it — by editing AGENTS.md/CLAUDE.md in interactive mode (with consent), or, in headless mode, by emitting a "Discoverability recommendation" line in the report rather than editing instruction files (per the headless boundary in step 4c — headless does doc maintenance, not project config). Either way the created file is surfaced or flagged for surfacing; subsequent runs skip this because the instruction file is already current or the recommendation was already reported.
Apply edits silently — no user prompt in any mode. Vocabulary capture is a side effect of refreshing, not a decision the user makes per run.
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.
After processing the selected scope, output the following report:
Compound Refresh Summary
========================
Scanned: N learnings
Kept: X
Updated: Y
Consolidated: C
Replaced: Z
Deleted: W
Skipped: V
Marked stale: S
CONCEPTS.md: <scanned, no qualifying terms | created with N entries (M seeded) | updated — N added, N refined, N reconciled, N scrubbed | repo-wide map created with N entries>
Then for EVERY file processed, list:
For Keep outcomes, list them under a reviewed-without-edits section so the result is visible without creating git churn.
In headless 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.
Split actions into two sections:
Applied (writes that succeeded):
Recommended (actions that could not be written — e.g., permission denied):
If 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.
Legacy cleanup (if <root>/solutions/_archived/ exists):
After 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).
Before offering options, check:
Use sensible defaults — no user to ask:
| Context | Default action |
|---|---|
| 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. |
| On a feature branch | Commit as a separate commit on the current branch |
| Git operations fail | Include the recommended git commands in the report and continue |
Stage only the files that compound-refresh modified — not other dirty files in the working tree.
First, 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.
If the current branch is main, master, or the repo's default branch:
docs/refresh-auth-learnings not docs/compound-refresh){current branch name}If the current branch is a feature branch, clean working tree:
{current branch name} as a separate commit (recommended)If the current branch is a feature branch, dirty working tree (other uncommitted changes):
{current branch name} (selective staging — other dirty files stay untouched)Write a descriptive commit message that:
ce-compound captures a newly solved, verified problemce-compound-refresh maintains older learnings as the codebase evolves — both their individual accuracy and their collective design as a document setUse 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.
Use 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.
After the refresh report is generated, check whether the project's instruction files would lead an agent to discover and search <root>/solutions/ before starting work in a documented area. This runs every time — the knowledge store only compounds value when agents can find it. If this check produces edits, they are committed as part of (or immediately after) the Phase 5 commit flow — see step 5 below.
Identify which root-level instruction files exist (AGENTS.md, CLAUDE.md, or both). Read the file(s) and determine which holds the substantive content — one file may just be a shim that @-includes the other (e.g., CLAUDE.md containing only @AGENTS.md, or vice versa). The substantive file is the assessment and edit target; ignore shims. If neither file exists, skip this check entirely.
Assess whether an agent reading the instruction files would learn three things:
module, tags, problem_type)This is a semantic assessment, not a string match. The information could be a line in an architecture section, a bullet in a gotchas section, spread across multiple places, or expressed without ever using the exact path <root>/solutions/. Use judgment — if an agent would reasonably discover and use the knowledge store after reading the file, the check passes.
If the spirit is already met, no action needed.
If not: a. Based on the file's existing structure, tone, and density, identify where a mention fits naturally. Before creating a new section, check whether the information could be a single line in the closest related section — an architecture tree, a directory listing, a documentation section, or a conventions block. A line added to an existing section is almost always better than a new headed section. Only add a new section as a last resort when the file has clear sectioned structure and nothing is even remotely related. b. Draft the smallest addition that communicates the three things. Match the file's existing style and density. The addition should describe the knowledge store itself, not the plugin.
Keep the tone informational, not imperative. Express timing as description, not instruction — "relevant when implementing or debugging in documented areas" rather than "check before implementing or debugging." Imperative directives like "always search before implementing" cause redundant reads when a workflow already includes a dedicated search step. The goal is awareness: agents learn the folder exists and what's in it, then use their own judgment about when to consult it.
Substitute the concrete root in what you write. The examples below show <root>/solutions/, but the instruction file is read by agents without this plugin (and by people), who cannot resolve <root>. When you insert the text, replace <root> with the resolved concrete path — the actual artifact directory, which is the default docs root's solutions/ unless a docs_root is configured — never the literal placeholder.
Examples of calibration (not templates — adapt to the file):
When there's an existing directory listing or architecture section — add a line:
<root>/solutions/ # documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (module, tags, problem_type)
When nothing in the file is a natural fit — a small headed section is appropriate:
## Documented Solutions
`<root>/solutions/` — documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (`module`, `tags`, `problem_type`). Relevant when implementing or debugging in documented areas.
c. In interactive mode, explain to the user why this matters — agents working in this repo (including fresh sessions, other tools, or collaborators without the plugin) won't know to check <root>/solutions/ unless the instruction file surfaces it. Show the proposed change and where it would go, then use the platform's blocking question tool to get consent before making the edit: AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), request_user_input in Codex, ask_question in Antigravity CLI (agy), ask_user in Pi (requires the pi-ask-user extension). Fall back to presenting the proposal in chat 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. In headless mode, include it as a "Discoverability recommendation" line in the report — do not attempt to edit instruction files (headless scope is doc maintenance, not project config).
If CONCEPTS.md exists at repo root, run a parallel discoverability check for it. Use the same workflow as the <root>/solutions/ check above: same target file, same edit-placement judgment, same consent-then-edit interaction shape per mode. Example calibration when a directory listing is present:
CONCEPTS.md # shared domain vocabulary — read when orienting to the codebase or before discussing domain concepts
Skip this step entirely if CONCEPTS.md does not exist — never nag for an artifact the project has not adopted. When skipped, this step produces no output and no edit.
Amend or create a follow-up commit when the check produces edits. If step 4 or step 5 resulted in an edit to an instruction file and Phase 5 already committed the refresh changes, stage the newly edited file and either amend the existing commit (if still on the same branch and no push has occurred) or create a small follow-up commit (e.g., docs: add <root>/solutions/ discoverability to AGENTS.md, or docs: add CONCEPTS.md discoverability to AGENTS.md, or a combined message when both edits landed). If Phase 5 already pushed the branch to a remote (e.g., the branch+PR path), push the follow-up commit as well so the open PR includes the discoverability change. This keeps the working tree clean and the remote in sync at the end of the run. If the user chose "Don't commit" in Phase 5, leave the instruction-file edits unstaged alongside the other uncommitted refresh changes — no separate commit logic needed.
Explore vague or ambitious ideas into a right-sized requirements-only unified plan. Use when the user wants to brainstorm, think through scope, decide what to build, or needs collaborative product framing before planning. Also use when the user must scope work in territory they say they do not know ("I know nothing about X but need to...") or asks for a blindspot pass — mapping the decision surface before questions begin. Not for executing already-specified work — direct implementation, debugging, or code review where no product scope is left to decide. Not for a decisive verdict on whether to adopt or switch to a specific external technology, library, or platform — brainstorming scopes what to build, not whether to commit to an outside option.
Structured code review for bugs, regressions, tests, and standards. Use before PRs or when asked for review; report-only by default, with explicit local apply available for user-directed fix workflows.
Document a recently solved problem as a durable repo learning, or capture project vocabulary in CONCEPTS.md. Use when capturing a learning after work.
Diagnosis loop for bugs and failing behavior. Use for errors, stack traces, regressions, failed tests, issue-tracker bugs, stuck investigations after failed fixes, or asks to debug/fix a bug.
Review requirements, plans, or specs with role-specific lenses. Use when the user wants to improve an existing planning document.
Create a durable, visual teaching artifact — plus an optional check-in (predict-then-reveal for diffs, corrected exercises) that makes it stick — for something worth learning: a concept, a diff, an idea, or a window of your own recent work. Use when the user wants to be taught, wants a deep explainer, wants to understand a substantial change, or wants a work recap built for retention. Not for ordinary Q&A, brief 'why?' follow-ups, operational diagnosis, status updates, or a concise trade-off answer that belongs inline in chat. For learning, not repo docs or verdicts.