ce-compound-refresh — Skillopedia

Compound Refresh Maintain the quality of 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 contains . If present, strip it from 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 | in arguments | No user interaction. Apply all unambiguous actions (Keep, Update, Consolid…

\n description: \"Date documented (YYYY-MM-DD)\"\n\n problem_type:\n type: enum\n values:\n - build_error\n - test_failure\n - runtime_error\n - performance_issue\n - database_issue\n - security_issue\n - ui_bug\n - integration_issue\n - logic_error\n - developer_experience\n - workflow_issue\n - best_practice\n - documentation_gap\n - architecture_pattern\n - design_pattern\n - tooling_decision\n - convention\n description: \"Primary category — determines track (bug vs knowledge). Prefer the narrowest applicable value; best_practice is the fallback when no narrower knowledge-track value fits.\"\n\n component:\n type: enum\n values:\n - rails_model\n - rails_controller\n - rails_view\n - service_object\n - background_job\n - database\n - frontend_stimulus\n - hotwire_turbo\n - email_processing\n - brief_system\n - assistant\n - authentication\n - payments\n - development_workflow\n - testing_framework\n - documentation\n - tooling\n description: \"Component involved\"\n\n severity:\n type: enum\n values:\n - critical\n - high\n - medium\n - low\n description: \"Impact severity\"\n\n# --- Track-specific rules ----------------------------------------------------\ntrack_rules:\n bug:\n required:\n symptoms:\n type: array[string]\n min_items: 1\n max_items: 5\n description: \"Observable symptoms such as errors or broken behavior\"\n root_cause:\n type: enum\n values:\n - missing_association\n - missing_include\n - missing_index\n - wrong_api\n - scope_issue\n - thread_violation\n - async_timing\n - memory_leak\n - config_error\n - logic_error\n - test_isolation\n - missing_validation\n - missing_permission\n - missing_workflow_step\n - inadequate_documentation\n - missing_tooling\n - incomplete_setup\n description: \"Fundamental technical cause of the problem\"\n resolution_type:\n type: enum\n values:\n - code_fix\n - migration\n - config_change\n - test_fix\n - dependency_update\n - environment_setup\n - workflow_improvement\n - documentation_update\n - tooling_addition\n - seed_data_update\n description: \"Type of fix applied\"\n\n knowledge:\n optional:\n applies_when:\n type: array[string]\n max_items: 5\n description: \"Conditions or situations where this guidance applies\"\n symptoms:\n type: array[string]\n max_items: 5\n description: \"Observable gaps or friction that prompted this guidance (optional for knowledge track)\"\n root_cause:\n type: enum\n values:\n - missing_association\n - missing_include\n - missing_index\n - wrong_api\n - scope_issue\n - thread_violation\n - async_timing\n - memory_leak\n - config_error\n - logic_error\n - test_isolation\n - missing_validation\n - missing_permission\n - missing_workflow_step\n - inadequate_documentation\n - missing_tooling\n - incomplete_setup\n description: \"Underlying cause, if there is a specific one (optional for knowledge track)\"\n resolution_type:\n type: enum\n values:\n - code_fix\n - migration\n - config_change\n - test_fix\n - dependency_update\n - environment_setup\n - workflow_improvement\n - documentation_update\n - tooling_addition\n - seed_data_update\n description: \"Type of change, if applicable (optional for knowledge track)\"\n\n# --- Fields optional for BOTH tracks ----------------------------------------\noptional_fields:\n related_components:\n type: array[string]\n description: \"Other components involved\"\n\n tags:\n type: array[string]\n max_items: 8\n description: \"Search keywords, lowercase and hyphen-separated\"\n\n# --- Fields optional for bug track only -------------------------------------\nbug_optional_fields:\n rails_version:\n type: string\n pattern: '^\\d+\\.\\d+\\.\\d+

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

\n description: \"Rails version in X.Y.Z format. Only relevant for bug-track docs.\"\n\n# --- Backward compatibility --------------------------------------------------\n# Docs created before the track system was introduced may have bug-track\n# fields (symptoms, root_cause, resolution_type) on knowledge-type\n# problem_types. These are valid legacy docs:\n# - Bug-track fields present on a knowledge-track doc are harmless. Do not\n# strip them during refresh unless the doc is being rewritten for other reasons.\n# - When creating NEW docs, follow the track rules above.\n\n# --- Validation rules --------------------------------------------------------\nvalidation_rules:\n - \"Determine track from problem_type using the tracks section above\"\n - \"All shared required_fields must be present\"\n - \"Bug-track required fields (symptoms, root_cause, resolution_type) must be present on bug-track docs\"\n - \"Knowledge-track docs have no additional required fields beyond the shared ones\"\n - \"Bug-track fields on existing knowledge-track docs are harmless (see backward compatibility note)\"\n - \"Track-specific optional fields may be included but are not required\"\n - \"Enum fields must match allowed values exactly\"\n - \"Array fields must respect min_items/max_items when specified\"\n - \"date must match YYYY-MM-DD format\"\n - \"rails_version, if provided, must match X.Y.Z format and only applies to bug-track docs\"\n - \"tags should be lowercase and hyphen-separated\"\n - \"Array-of-strings frontmatter items (symptoms, applies_when, tags, related_components, or any future array field) must be wrapped in double quotes when the value starts with a YAML reserved indicator (`, [, *, &, !, |, >, %, @, ?) or contains the substring `: ` — otherwise strict YAML parsers reject the file\"\n","content_type":"application/yaml; charset=utf-8","language":"yaml","size":7623,"content_sha256":"f6d9e2682d9f98742dd12319c05d4715b7d7123d6585a6404deb18c6542c2c24"},{"filename":"references/yaml-schema.md","content":"# YAML Frontmatter Schema\n\n`schema.yaml` in this directory is the canonical contract for `docs/solutions/` frontmatter written by `ce-compound`.\n\nUse this file as the quick reference for:\n- required fields\n- enum values\n- validation expectations\n- category mapping\n- track classification (bug vs knowledge)\n\n## Tracks\n\nThe `problem_type` determines which **track** applies. Each track has different required and optional fields.\n\n| Track | problem_types | Description |\n|-------|--------------|-------------|\n| **Bug** | `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error` | Defects and failures that were diagnosed and fixed |\n| **Knowledge** | `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`, `architecture_pattern`, `design_pattern`, `tooling_decision`, `convention` | Practices, patterns, conventions, decisions, workflow improvements, and documentation. Prefer the narrowest applicable value; `best_practice` is the fallback. |\n\n## Required Fields (both tracks)\n\n- **module**: Module or area affected\n- **date**: ISO date in `YYYY-MM-DD`\n- **problem_type**: One of the values listed in the Tracks table above\n- **component**: One of `rails_model`, `rails_controller`, `rails_view`, `service_object`, `background_job`, `database`, `frontend_stimulus`, `hotwire_turbo`, `email_processing`, `brief_system`, `assistant`, `authentication`, `payments`, `development_workflow`, `testing_framework`, `documentation`, `tooling`\n- **severity**: One of `critical`, `high`, `medium`, `low`\n\n## Bug Track Fields\n\nRequired:\n- **symptoms**: YAML array with 1-5 observable symptoms (errors, broken behavior)\n- **root_cause**: One of `missing_association`, `missing_include`, `missing_index`, `wrong_api`, `scope_issue`, `thread_violation`, `async_timing`, `memory_leak`, `config_error`, `logic_error`, `test_isolation`, `missing_validation`, `missing_permission`, `missing_workflow_step`, `inadequate_documentation`, `missing_tooling`, `incomplete_setup`\n- **resolution_type**: One of `code_fix`, `migration`, `config_change`, `test_fix`, `dependency_update`, `environment_setup`, `workflow_improvement`, `documentation_update`, `tooling_addition`, `seed_data_update`\n\n## Knowledge Track Fields\n\nNo additional required fields beyond the shared ones. All fields below are optional:\n\n- **applies_when**: Conditions or situations where this guidance applies\n- **symptoms**: Observable gaps or friction that prompted this guidance\n- **root_cause**: Underlying cause, if there is a specific one\n- **resolution_type**: Type of change, if applicable\n\n## Optional Fields (both tracks)\n\n- **related_components**: Other components involved\n- **tags**: Search keywords, lowercase and hyphen-separated\n\n## Optional Fields (bug track only)\n\n- **rails_version**: Rails version in `X.Y.Z` format\n\n## Backward Compatibility\n\nDocs created before the track system may have `symptoms`/`root_cause`/`resolution_type` on knowledge-type problem_types. These are valid legacy docs:\n\n- Bug-track fields present on a knowledge-track doc are harmless. Do not strip them during refresh unless the doc is being rewritten for other reasons.\n- When creating **new** docs, follow the track rules above.\n\n## Category Mapping\n\n- `build_error` -> `docs/solutions/build-errors/`\n- `test_failure` -> `docs/solutions/test-failures/`\n- `runtime_error` -> `docs/solutions/runtime-errors/`\n- `performance_issue` -> `docs/solutions/performance-issues/`\n- `database_issue` -> `docs/solutions/database-issues/`\n- `security_issue` -> `docs/solutions/security-issues/`\n- `ui_bug` -> `docs/solutions/ui-bugs/`\n- `integration_issue` -> `docs/solutions/integration-issues/`\n- `logic_error` -> `docs/solutions/logic-errors/`\n- `developer_experience` -> `docs/solutions/developer-experience/`\n- `workflow_issue` -> `docs/solutions/workflow-issues/`\n- `best_practice` -> `docs/solutions/best-practices/`\n- `documentation_gap` -> `docs/solutions/documentation-gaps/`\n- `architecture_pattern` -> `docs/solutions/architecture-patterns/`\n- `design_pattern` -> `docs/solutions/design-patterns/`\n- `tooling_decision` -> `docs/solutions/tooling-decisions/`\n- `convention` -> `docs/solutions/conventions/`\n\n## Validation Rules\n\n1. Determine the track from `problem_type` using the Tracks table.\n2. All shared required fields must be present.\n3. Bug-track required fields (`symptoms`, `root_cause`, `resolution_type`) must be present on bug-track docs.\n4. Knowledge-track docs have no additional required fields beyond the shared ones.\n5. Bug-track fields on existing knowledge-track docs are harmless (see Backward Compatibility).\n6. Enum fields must match the allowed values exactly.\n7. Array fields must respect min/max item counts.\n8. `date` must match `YYYY-MM-DD`.\n9. `rails_version`, if present, must match `X.Y.Z` and only applies to bug-track docs.\n\n## YAML Safety Rules\n\nStrict YAML 1.2 parsers (`yq`, `js-yaml` strict, PyYAML) reject array items\nthat start with a reserved indicator character as unquoted scalars. When\nwriting items for any array-of-strings field (`symptoms`, `applies_when`,\n`tags`, `related_components`, or any future array field), wrap the value in\ndouble quotes if it starts with any of:\n\n`` ` ``, `[`, `*`, `&`, `!`, `|`, `>`, `%`, `@`, `?`\n\nAlso quote if the value contains the substring `\": \"` — that punctuation\nconfuses flow-style parsers.\n\nExample — before (breaks strict YAML):\n\n symptoms:\n - `sudo dscacheutil -flushcache` does not restore in-container mDNS\n\nExample — after (parses cleanly):\n\n symptoms:\n - \"`sudo dscacheutil -flushcache` does not restore in-container mDNS\"\n\nThis rule applies to all array-of-strings frontmatter fields. Scalar string\nfields like `description:` have their own quoting rules (see plugin\n`AGENTS.md` under \"YAML Frontmatter\").\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5880,"content_sha256":"079395c03f6abf89ac95e227ec31b9db13de6bc414ca7fbe0fc72fcbfa1a53d7"},{"filename":"scripts/validate-frontmatter.py","content":"#!/usr/bin/env python3\n\"\"\"Validate ce-compound docs/solutions/ frontmatter for parser-safety issues.\n\nUsage:\n python3 validate-frontmatter.py \u003cdoc-path>\n\nExit codes:\n 0 — frontmatter passes all checks\n 1 — validation failure (diagnostics on stderr)\n 2 — usage error (bad arguments, missing file)\n\nScope: this script catches *parser-safety* issues — frontmatter that strict\nYAML parsers will silently misread. It does NOT validate against the\nschema's required-field or enum-value rules; that's a separate concern. The\nintent is to prevent the silent-data-loss bug class where YAML's quoting\nrules truncate or reframe scalar values without raising.\n\nChecks (regex-based, no YAML parser dependency):\n 1. File starts and ends frontmatter with `---` lines (matched as full\n lines, not substrings — `----` and `---extra` are rejected)\n 2. No top-level scalar value contains ` #` unquoted (silent comment\n truncation — what Codex caught on PR #695)\n 3. No top-level scalar value contains `: ` unquoted (mapping confusion —\n what surfaced in a 2026-04-16 plan doc's `title:` field)\n\nThe script does NOT flag values starting with YAML reserved indicators\n(`` ` ``, `*`, `&`, `!`, etc.) because those produce loud parser errors\ndownstream rather than silent corruption — they're already caught by\nwhatever consumes the doc. This validator's purpose is silent-corruption\nprevention, not lint.\n\nPure-stdlib (no PyYAML or other third-party deps). Runs in \u003c50ms typical.\nDesigned to produce concrete, actionable error messages so the calling\nagent can fix and retry without ambiguity.\n\"\"\"\nimport os\nimport re\nimport sys\n\n\ndef usage_fail(msg: str) -> \"NoReturn\":\n sys.stderr.write(f\"validate-frontmatter: {msg}\\n\")\n sys.exit(2)\n\n\ndef main(argv: list[str]) -> int:\n if len(argv) != 2:\n usage_fail(f\"usage: {os.path.basename(argv[0])} \u003cdoc-path>\")\n\n doc_path = argv[1]\n if not os.path.isfile(doc_path):\n usage_fail(f\"file not found: {doc_path}\")\n\n with open(doc_path) as f:\n text = f.read()\n\n issues: list[str] = []\n\n # Check 1: frontmatter delimiters. Match the delimiter as a complete\n # line whose stripped content is exactly `---` — substring matching\n # (e.g. `text.find(\"\\n---\", 4)`) would falsely accept `----` or\n # `---extra` as a terminator and let malformed docs slip through to\n # downstream parsers that require a strict `---` line.\n lines = text.split(\"\\n\")\n if not lines or lines[0].rstrip() != \"---\":\n sys.stderr.write(\n f\"FAIL: {doc_path}\\n\"\n f\" file does not start with '---' frontmatter delimiter line\\n\"\n )\n return 1\n\n end_idx: int | None = None\n for i in range(1, len(lines)):\n if lines[i].rstrip() == \"---\":\n end_idx = i\n break\n\n if end_idx is None:\n sys.stderr.write(\n f\"FAIL: {doc_path}\\n\"\n f\" frontmatter not closed (no '---' line after the opening delimiter)\\n\"\n )\n return 1\n\n fm_text = \"\\n\".join(lines[1:end_idx])\n\n # Checks 2 & 3: silent-corruption quoting risks on top-level scalar\n # fields. We scan line-by-line and only flag top-level mapping entries\n # (no leading whitespace) whose value isn't already quoted/structured.\n for lineno, line in enumerate(fm_text.split(\"\\n\"), start=2):\n stripped = line.lstrip()\n if not stripped or stripped.startswith(\"#\"):\n continue\n if \":\" not in line:\n continue\n # Top-level mapping keys only — skip nested values, array items\n if line.startswith((\" \", \"\\t\")):\n continue\n # Skip pure list-marker lines like \"- item\" (these can't be top-level\n # in our frontmatter convention, but be defensive)\n if stripped.startswith(\"- \"):\n continue\n\n key, _, val = line.partition(\":\")\n val_stripped = val.strip()\n if not val_stripped:\n # Key with no value on this line — likely a parent of a nested\n # block (`tags:` followed by `- foo`). Nothing to validate here.\n continue\n # Already quoted or structured (block scalar, flow collection)\n if val_stripped[0] in '\"\\'[{|>':\n continue\n\n if re.search(r\"\\s#\", val_stripped):\n issues.append(\n f\"line {lineno}: '{key.strip()}' value contains ' #' — quote it. \"\n \"YAML treats space-then-# as a comment delimiter and silently \"\n \"drops the rest of the value.\"\n )\n if re.search(r\":\\s\", val_stripped):\n issues.append(\n f\"line {lineno}: '{key.strip()}' value contains ': ' — quote it. \"\n \"Strict YAML parsers may treat this as a nested mapping.\"\n )\n\n if issues:\n sys.stderr.write(f\"FAIL: {doc_path}\\n\")\n for issue in issues:\n sys.stderr.write(f\" {issue}\\n\")\n return 1\n\n print(f\"OK: {doc_path}\")\n return 0\n\n\nif __name__ == \"__main__\":\n sys.exit(main(sys.argv))\n","content_type":"text/x-python; charset=utf-8","language":"python","size":5063,"content_sha256":"c165f67c1885875672d45cd447dc75968589a7bb00982c33140fe925d510cf89"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Compound Refresh","type":"text"}]},{"type":"paragraph","content":[{"text":"Maintain the quality of ","type":"text"},{"text":"docs/solutions/","type":"text","marks":[{"type":"code_inline"}]},{"text":" over time. This workflow reviews existing learnings against the current codebase, then refreshes any derived pattern docs that depend on them.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Mode Detection","type":"text"}]},{"type":"paragraph","content":[{"text":"Check if ","type":"text"},{"text":"$ARGUMENTS","type":"text","marks":[{"type":"code_inline"}]},{"text":" contains ","type":"text"},{"text":"mode:headless","type":"text","marks":[{"type":"code_inline"}]},{"text":". If present, strip it from arguments (use the remainder as a scope hint) and run in ","type":"text"},{"text":"headless mode","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mode","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Behavior","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Interactive","type":"text","marks":[{"type":"strong"}]},{"text":" (default)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"User is present and can answer questions","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Ask for decisions on ambiguous cases, confirm actions","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Headless","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"mode:headless","type":"text","marks":[{"type":"code_inline"}]},{"text":" in arguments","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Headless mode rules","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skip all user questions.","type":"text","marks":[{"type":"strong"}]},{"text":" Never pause for input.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Process all docs in scope.","type":"text","marks":[{"type":"strong"}]},{"text":" No scope narrowing questions — if no scope hint was provided, process everything.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Attempt all safe actions:","type":"text","marks":[{"type":"strong"}]},{"text":" 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 ","type":"text"},{"text":"applied","type":"text","marks":[{"type":"strong"}]},{"text":". If a write fails (e.g., permission denied), record the action as ","type":"text"},{"text":"recommended","type":"text","marks":[{"type":"strong"}]},{"text":" in the report and continue — do not stop or ask for permissions.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Mark as stale when uncertain.","type":"text","marks":[{"type":"strong"}]},{"text":" If classification is genuinely ambiguous (Update vs Replace vs Consolidate vs Delete) or Replace evidence is insufficient, mark as stale with ","type":"text"},{"text":"status: stale","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"stale_reason","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"stale_date","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the frontmatter. If even the stale-marking write fails, include it as a recommendation.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use conservative confidence.","type":"text","marks":[{"type":"strong"}]},{"text":" In interactive mode, borderline cases get a user question. In headless mode, borderline cases get marked stale. Err toward stale-marking over incorrect action.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Always generate a report.","type":"text","marks":[{"type":"strong"}]},{"text":" The report is the primary deliverable. It has two sections: ","type":"text"},{"text":"Applied","type":"text","marks":[{"type":"strong"}]},{"text":" (actions that were successfully written) and ","type":"text"},{"text":"Recommended","type":"text","marks":[{"type":"strong"}]},{"text":" (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.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Interaction Principles","type":"text"}]},{"type":"paragraph","content":[{"text":"These principles apply to interactive mode only. In headless mode, skip all user questions and apply the headless mode rules above.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Follow the same interaction style as ","type":"text"},{"text":"ce-brainstorm","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ask questions ","type":"text"},{"text":"one at a time","type":"text","marks":[{"type":"strong"}]},{"text":" — use the platform's blocking question tool: ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Claude Code (call ","type":"text"},{"text":"ToolSearch","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"select:AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" first if its schema isn't loaded), ","type":"text"},{"text":"request_user_input","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Codex, ","type":"text"},{"text":"ask_user","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Gemini, ","type":"text"},{"text":"ask_user","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Pi (requires the ","type":"text"},{"text":"pi-ask-user","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prefer ","type":"text"},{"text":"multiple choice","type":"text","marks":[{"type":"strong"}]},{"text":" when natural options exist","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Start with ","type":"text"},{"text":"scope and intent","type":"text","marks":[{"type":"strong"}]},{"text":", then narrow only when needed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" ask the user to make decisions before you have evidence","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lead with a recommendation and explain it briefly","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Refresh Order","type":"text"}]},{"type":"paragraph","content":[{"text":"Refresh in this order:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review the relevant individual learning docs first","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Note which learnings stayed valid, were updated, were consolidated, were replaced, or were deleted","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Then review any pattern docs that depend on those learnings","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Why this order:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"learning docs are the primary evidence","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"pattern docs are derived from one or more learnings","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"stale learnings can make a pattern look more valid than it really is","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Maintenance Model","type":"text"}]},{"type":"paragraph","content":[{"text":"For each candidate artifact, classify it into one of five outcomes:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Outcome","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Meaning","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Default action","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Keep","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Still accurate and still useful","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No file edit by default; report that it was reviewed and remains trustworthy","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Update","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Core solution is still correct, but references drifted","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Apply evidence-backed in-place edits","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Consolidate","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Two or more docs overlap heavily but are both correct","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Merge unique content into the canonical doc, delete the subsumed doc","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Replace","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"The old artifact is now misleading, but there is a known better replacement","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Create a trustworthy successor, then delete the old artifact","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Delete","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No longer useful, applicable, or distinct","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Delete the file — git history preserves it if anyone needs to recover it later","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Core Rules","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Evidence informs judgment.","type":"text","marks":[{"type":"strong"}]},{"text":" The signals below are inputs, not a mechanical scorecard. Use engineering judgment to decide whether the artifact is still trustworthy.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prefer no-write Keep.","type":"text","marks":[{"type":"strong"}]},{"text":" Do not update a doc just to leave a review breadcrumb.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Match docs to reality, not the reverse.","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Be decisive, minimize questions.","type":"text","marks":[{"type":"strong"}]},{"text":" 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 headless 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.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Avoid low-value churn.","type":"text","marks":[{"type":"strong"}]},{"text":" Do not edit a doc just to fix a typo, polish wording, or make cosmetic changes that do not materially improve accuracy or usability.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use Update only for meaningful, evidence-backed drift.","type":"text","marks":[{"type":"strong"}]},{"text":" Paths, module names, related links, category metadata, code snippets, and clearly stale wording are fair game when fixing them materially improves accuracy.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use Replace only when there is a real replacement.","type":"text","marks":[{"type":"strong"}]},{"text":" That means either:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"the current conversation contains a recently solved, verified replacement fix, or","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"the user has provided enough concrete replacement context to document the successor honestly, or","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"the codebase investigation found the current approach and can document it as the successor, or","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"newer docs, pattern docs, PRs, or issues provide strong successor evidence.","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Delete when the code is gone, and only after checking for inbound links.","type":"text","marks":[{"type":"strong"}]},{"text":" 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.\" When in doubt between Keep and Delete, ask the user (in interactive mode) or mark as stale (in headless mode). Inbound links inform classification, not cleanup: cleanup is always mechanical, but ","type":"text"},{"text":"decorative","type":"text","marks":[{"type":"strong"}]},{"text":" citations (principle stated inline) allow Delete, while ","type":"text"},{"text":"substantive","type":"text","marks":[{"type":"strong"}]},{"text":" citations (citing doc relies on the cited doc) signal Replace. The auto-delete case is missing code, no matching successor, and citations absent or decorative.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Evaluate document-set design, not just accuracy.","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Delete, don't archive.","type":"text","marks":[{"type":"strong"}]},{"text":" There is no ","type":"text"},{"text":"_archived/","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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, ","type":"text"},{"text":"git log --diff-filter=D -- docs/solutions/","type":"text","marks":[{"type":"code_inline"}]},{"text":" will find it.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Scope Selection","type":"text"}]},{"type":"paragraph","content":[{"text":"Start by discovering learnings and pattern docs under ","type":"text"},{"text":"docs/solutions/","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Exclude:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"README.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"docs/solutions/_archived/","type":"text","marks":[{"type":"code_inline"}]},{"text":" (legacy — if this directory exists, flag it for cleanup in the report)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Find all ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files under ","type":"text"},{"text":"docs/solutions/","type":"text","marks":[{"type":"code_inline"}]},{"text":", excluding ","type":"text"},{"text":"README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" files and anything under ","type":"text"},{"text":"_archived/","type":"text","marks":[{"type":"code_inline"}]},{"text":". If an ","type":"text"},{"text":"_archived/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory exists, note it in the report as a legacy artifact that should be cleaned up (files either restored or deleted).","type":"text"}]},{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"$ARGUMENTS","type":"text","marks":[{"type":"code_inline"}]},{"text":" is provided, use it to narrow scope before proceeding. Try these matching strategies in order, stopping at the first that produces results:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Directory match","type":"text","marks":[{"type":"strong"}]},{"text":" — check if the argument matches a subdirectory name under ","type":"text"},{"text":"docs/solutions/","type":"text","marks":[{"type":"code_inline"}]},{"text":" (e.g., ","type":"text"},{"text":"performance-issues","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"database-issues","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Frontmatter match","type":"text","marks":[{"type":"strong"}]},{"text":" — search ","type":"text"},{"text":"module","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"component","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"tags","type":"text","marks":[{"type":"code_inline"}]},{"text":" fields in learning frontmatter for the argument","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Filename match","type":"text","marks":[{"type":"strong"}]},{"text":" — match against filenames (partial matches are fine)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Content search","type":"text","marks":[{"type":"strong"}]},{"text":" — search file contents for the argument as a keyword (useful for feature names or feature areas)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If 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 ","type":"text"},{"text":"no","type":"text","marks":[{"type":"strong"}]},{"text":" scope hint was provided.)","type":"text"}]},{"type":"paragraph","content":[{"text":"If no candidate docs are found, report:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"text"},"content":[{"text":"No candidate docs found in docs/solutions/.\nRun `ce-compound` after solving problems to start building your knowledge base.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 0: Assess and Route","type":"text"}]},{"type":"paragraph","content":[{"text":"Before asking the user to classify anything:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Discover candidate artifacts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Estimate scope","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Choose the lightest interaction path that fits","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Route by Scope","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Scope","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When to use it","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Interaction style","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Focused","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"1-2 likely files or user named a specific doc","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Investigate directly, then present a recommendation","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Batch","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Up to ~8 mostly independent docs","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Investigate first, then present grouped recommendations","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Broad","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"9+ docs, ambiguous, or repo-wide stale-doc sweep","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Triage first, then investigate in batches","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Broad Scope Triage","type":"text"}]},{"type":"paragraph","content":[{"text":"When scope is broad (9+ candidate docs), do a lightweight triage before deep investigation:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Inventory","type":"text","marks":[{"type":"strong"}]},{"text":" — read frontmatter of all candidate docs, group by module/component/category","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Impact clustering","type":"text","marks":[{"type":"strong"}]},{"text":" — 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.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Spot-check drift","type":"text","marks":[{"type":"strong"}]},{"text":" — for each cluster, check whether the primary referenced files still exist. Missing references in a high-impact cluster = strongest signal for where to start.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recommend a starting area","type":"text","marks":[{"type":"strong"}]},{"text":" — present the highest-impact cluster with a brief rationale and ask the user to confirm or redirect. In headless mode, skip the question and process all clusters in impact order.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"text"},"content":[{"text":"Found 24 learnings across 5 areas.\n\nThe auth module has 5 learnings and 2 pattern docs that cross-reference\neach other — and 3 of those reference files that no longer exist.\nI'd start there.\n\n1. Start with auth (recommended)\n2. Pick a different area\n3. Review everything","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not ask action-selection questions yet. First gather evidence.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 1: Investigate Candidate Learnings","type":"text"}]},{"type":"paragraph","content":[{"text":"For each learning in scope, read it, cross-reference its claims against the current codebase, and form a recommendation.","type":"text"}]},{"type":"paragraph","content":[{"text":"A learning has several dimensions that can independently go stale. Surface-level checks catch the obvious drift, but staleness often hides deeper:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"References","type":"text","marks":[{"type":"strong"}]},{"text":" — do the file paths, class names, and modules it mentions still exist or have they moved?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recommended solution","type":"text","marks":[{"type":"strong"}]},{"text":" — 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.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code examples","type":"text","marks":[{"type":"strong"}]},{"text":" — if the learning includes code snippets, do they still reflect the current implementation?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Related docs","type":"text","marks":[{"type":"strong"}]},{"text":" — are cross-referenced learnings and patterns still present and consistent?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auto memory","type":"text","marks":[{"type":"strong"}]},{"text":" (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.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Overlap","type":"text","marks":[{"type":"strong"}]},{"text":" — 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).","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Drift Classification: Update vs Replace","type":"text"}]},{"type":"paragraph","content":[{"text":"The critical distinction is whether the drift is ","type":"text"},{"text":"cosmetic","type":"text","marks":[{"type":"strong"}]},{"text":" (references moved but the solution is the same) or ","type":"text"},{"text":"substantive","type":"text","marks":[{"type":"strong"}]},{"text":" (the solution itself changed):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update territory","type":"text","marks":[{"type":"strong"}]},{"text":" — file paths moved, classes renamed, links broke, metadata drifted, but the core recommended approach is still how the code works. ","type":"text"},{"text":"ce-compound-refresh","type":"text","marks":[{"type":"code_inline"}]},{"text":" fixes these directly.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Replace territory","type":"text","marks":[{"type":"strong"}]},{"text":" — 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 ","type":"text"},{"text":"ce-compound","type":"text","marks":[{"type":"code_inline"}]},{"text":"'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.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The boundary:","type":"text","marks":[{"type":"strong"}]},{"text":" if you find yourself rewriting the solution section or changing what the learning recommends, stop — that is Replace, not Update.","type":"text"}]},{"type":"paragraph","content":[{"text":"Memory-sourced drift signals","type":"text","marks":[{"type":"strong"}]},{"text":" are supplementary, not primary. A memory note describing a different approach does not alone justify Replace or Delete. Use memory signals to:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Corroborate codebase-sourced drift (strengthens the case for Replace)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prompt deeper investigation when codebase evidence is borderline","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add context to the evidence report (\"(auto memory [claude]) notes suggest approach X may have changed since this learning was written\")","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"In headless mode, memory-only drift (no codebase corroboration) should result in stale-marking, not action.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Judgment Guidelines","type":"text"}]},{"type":"paragraph","content":[{"text":"Three guidelines that are easy to get wrong:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Contradiction = strong Replace signal.","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Age alone is not a stale signal.","type":"text","marks":[{"type":"strong"}]},{"text":" A 2-year-old learning that still matches current code is fine. Only use age as a prompt to inspect more carefully.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check for successors before deleting.","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 1.5: Investigate Pattern Docs","type":"text"}]},{"type":"paragraph","content":[{"text":"After reviewing the underlying learning docs, investigate any relevant pattern docs under ","type":"text"},{"text":"docs/solutions/patterns/","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"A pattern doc with no clear supporting learnings is a stale signal — investigate carefully before keeping it unchanged.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 1.75: Document-Set Analysis","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Overlap Detection","type":"text"}]},{"type":"paragraph","content":[{"text":"For docs that share the same module, component, tags, or problem domain, compare them across these dimensions:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Problem statement","type":"text","marks":[{"type":"strong"}]},{"text":" — do they describe the same underlying problem?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Solution shape","type":"text","marks":[{"type":"strong"}]},{"text":" — do they recommend the same approach, even if worded differently?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Referenced files","type":"text","marks":[{"type":"strong"}]},{"text":" — do they point to the same code paths?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prevention rules","type":"text","marks":[{"type":"strong"}]},{"text":" — do they repeat the same prevention bullets?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Root cause","type":"text","marks":[{"type":"strong"}]},{"text":" — do they identify the same root cause?","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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?\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Supersession Signals","type":"text"}]},{"type":"paragraph","content":[{"text":"Detect \"older narrow precursor, newer canonical doc\" patterns:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A newer doc covers the same files, same workflow, and broader runtime behavior than an older doc","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"An older doc describes a specific incident that a newer doc generalizes into a pattern","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Two docs recommend the same fix but the newer one has better context, examples, or scope","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Canonical Doc Identification","type":"text"}]},{"type":"paragraph","content":[{"text":"For each topic cluster (docs sharing a problem domain), identify which doc is the ","type":"text"},{"text":"canonical source of truth","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Usually the most recent, broadest, most accurate doc in the cluster","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The one a maintainer should find first when searching for this topic","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The one that other docs should point to, not duplicate","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"All other docs in the cluster are either:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Distinct","type":"text","marks":[{"type":"strong"}]},{"text":" — they cover a meaningfully different sub-problem and have independent retrieval value. Keep them separate.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Subsumed","type":"text","marks":[{"type":"strong"}]},{"text":" — their unique content fits as a section in the canonical doc. Consolidate.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Redundant","type":"text","marks":[{"type":"strong"}]},{"text":" — they add nothing the canonical doc doesn't already say. Delete.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Retrieval-Value Test","type":"text"}]},{"type":"paragraph","content":[{"text":"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?\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Separate docs earn their keep only when:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"They cover genuinely different sub-problems that someone might search for independently","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"They target different audiences or contexts (e.g., one is about debugging, another about prevention)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Merging them would create an unwieldy doc that is harder to navigate than two focused ones","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Cross-Doc Conflict Check","type":"text"}]},{"type":"paragraph","content":[{"text":"Look for outright contradictions between docs in scope:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Doc A says \"always use approach X\" while Doc B says \"avoid approach X\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Doc A references a file path that Doc B says was deprecated","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Doc A and Doc B describe different root causes for what appears to be the same problem","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Subagent Strategy","type":"text"}]},{"type":"paragraph","content":[{"text":"Use subagents for context isolation when investigating multiple artifacts — not just because the task sounds complex. Choose the lightest approach that fits:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Approach","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When to use","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Main thread only","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Small scope, short docs","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Sequential subagents","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"1-2 artifacts with many supporting files to read","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Parallel subagents","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"3+ truly independent artifacts with low overlap","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Batched subagents","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Broad sweeps — narrow scope first, then investigate in batches","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"When spawning any subagent","type":"text","marks":[{"type":"strong"}]},{"text":", omit the ","type":"text"},{"text":"mode","type":"text","marks":[{"type":"code_inline"}]},{"text":" parameter so the user's configured permission settings apply. Include this instruction in its task prompt:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"There are two subagent roles:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Investigation subagents","type":"text","marks":[{"type":"strong"}]},{"text":" — 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.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Replacement subagents","type":"text","marks":[{"type":"strong"}]},{"text":" — write a single new learning to replace a stale one. These run ","type":"text"},{"text":"one at a time, sequentially","type":"text","marks":[{"type":"strong"}]},{"text":" (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.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 2: Classify the Right Maintenance Action","type":"text"}]},{"type":"paragraph","content":[{"text":"After gathering evidence, assign one recommended action.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Keep","type":"text"}]},{"type":"paragraph","content":[{"text":"The learning is still accurate and useful. Do not edit the file — report that it was reviewed and remains trustworthy. Only add ","type":"text"},{"text":"last_refreshed","type":"text","marks":[{"type":"code_inline"}]},{"text":" if you are already making a meaningful update for another reason.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Update","type":"text"}]},{"type":"paragraph","content":[{"text":"The core solution is still valid but references have drifted (paths, class names, links, code snippets, metadata). Apply the fixes directly.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Consolidate","type":"text"}]},{"type":"paragraph","content":[{"text":"Choose ","type":"text"},{"text":"Consolidate","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"When to consolidate:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Two docs describe the same problem and recommend the same (or compatible) solution","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"One doc is a narrow precursor and a newer doc covers the same ground more broadly","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The unique content from the subsumed doc can fit as a section or addendum in the canonical doc","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keeping both creates drift risk without meaningful retrieval benefit","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"When NOT to consolidate","type":"text","marks":[{"type":"strong"}]},{"text":" (apply the Retrieval-Value Test from Phase 1.75):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The docs cover genuinely different sub-problems that someone would search for independently","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Merging would create an unwieldy doc that harms navigation more than drift risk harms accuracy","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Consolidate vs Delete:","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Replace","type":"text"}]},{"type":"paragraph","content":[{"text":"Choose ","type":"text"},{"text":"Replace","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Evidence assessment:","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Sufficient evidence","type":"text","marks":[{"type":"strong"}]},{"text":" — 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).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Insufficient evidence","type":"text","marks":[{"type":"strong"}]},{"text":" — 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:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add ","type":"text"},{"text":"status: stale","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"stale_reason: [what you found]","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"stale_date: YYYY-MM-DD","type":"text","marks":[{"type":"code_inline"}]},{"text":" to the frontmatter","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Report what evidence you found and what is missing","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recommend the user run ","type":"text"},{"text":"ce-compound","type":"text","marks":[{"type":"code_inline"}]},{"text":" after their next encounter with that area, when they have fresh problem-solving context","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Delete","type":"text"}]},{"type":"paragraph","content":[{"text":"Choose ","type":"text"},{"text":"Delete","type":"text","marks":[{"type":"strong"}]},{"text":" when:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The code or workflow no longer exists and the problem domain is gone","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The learning is obsolete and has no modern replacement worth documenting","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The learning is fully redundant with another doc (use Consolidate if there is unique content to merge first)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"There is no meaningful successor evidence suggesting it should be replaced instead","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Action: delete the file. No archival directory, no metadata — just delete it. Git history preserves every deleted file if recovery is ever needed.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Before deleting: check if the problem domain is still active","type":"text"}]},{"type":"paragraph","content":[{"text":"When a learning's referenced files are gone, that is strong evidence — but only that the ","type":"text"},{"text":"implementation","type":"text","marks":[{"type":"strong"}]},{"text":" is gone. Before deleting, reason about whether the ","type":"text"},{"text":"problem the learning solves","type":"text","marks":[{"type":"strong"}]},{"text":" is still a concern in the codebase:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A learning about session token storage where ","type":"text"},{"text":"auth_token.rb","type":"text","marks":[{"type":"code_inline"}]},{"text":" is gone — does the application still handle session tokens? If so, the concept persists under a new implementation. That is Replace, not Delete.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A learning about a deprecated API endpoint where the entire feature was removed — the problem domain is gone. That is Delete.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Before deleting: check for inbound links","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Search efficiently:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prefer the platform's native content-search tool (e.g., Grep in Claude Code) over shell. Drop to shell when materially better for the case.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Search the filename slug (without ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":"); narrow to the full path only if matches are noisy.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read context lines around each match (e.g., Grep's ","type":"text"},{"text":"-B","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"-A","type":"text","marks":[{"type":"code_inline"}]},{"text":"), not whole files.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Inbound links inform the classification, not the cleanup.","type":"text","marks":[{"type":"strong"}]},{"text":" 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?","type":"text"}]},{"type":"paragraph","content":[{"text":"Classify each citation by what it does in its citing context:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Decorative","type":"text","marks":[{"type":"strong"}]},{"text":" — principle stated inline, citation is a \"see also\" pointer or bare attribution. Delete is fine; clean up citations in the same commit.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Substantive","type":"text","marks":[{"type":"strong"}]},{"text":" — citing doc relies on the cited doc to provide content not stated inline (e.g., \"see X for details on Y\" with no inline Y). Signal Replace — write a successor at the same path, or ","type":"text"},{"text":"Keep with narrowed scope","type":"text","marks":[{"type":"strong"}]},{"text":" if the doc's actual content is broader than its title implies.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Mixed or unclear","type":"text","marks":[{"type":"strong"}]},{"text":" — stale-mark.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Auto-delete only when all three hold:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The implementation is gone (or fully superseded by a clearly better successor, or the doc is plainly redundant).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The problem domain is gone — the app no longer deals with what the learning addresses.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Inbound links are absent or unambiguously decorative.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Pattern Guidance","type":"text"}]},{"type":"paragraph","content":[{"text":"Apply the same five outcomes (Keep, Update, Consolidate, Replace, Delete) to pattern docs, but evaluate them as ","type":"text"},{"text":"derived guidance","type":"text","marks":[{"type":"strong"}]},{"text":" rather than incident-level learnings. Key differences:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep","type":"text","marks":[{"type":"strong"}]},{"text":": the underlying learnings still support the generalized rule and examples remain representative","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update","type":"text","marks":[{"type":"strong"}]},{"text":": the rule holds but examples, links, scope, or supporting references drifted","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Consolidate","type":"text","marks":[{"type":"strong"}]},{"text":": two pattern docs generalize the same set of learnings or cover the same design concern — merge into one canonical pattern","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Replace","type":"text","marks":[{"type":"strong"}]},{"text":": 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","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Delete","type":"text","marks":[{"type":"strong"}]},{"text":": the pattern is no longer valid, no longer recurring, or fully subsumed by a stronger pattern doc with no unique content remaining","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 3: Ask for Decisions","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Headless mode","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip this entire phase. Do not ask any questions. Do not present options. Do not wait for input.","type":"text","marks":[{"type":"strong"}]},{"text":" Proceed directly to Phase 4 and execute all actions based on the classifications from Phase 2:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Unambiguous Keep, Update, Consolidate, auto-Delete, and Replace (with sufficient evidence) → execute directly","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ambiguous cases → mark as stale","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Then generate the report (see Output Format)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Interactive mode","type":"text"}]},{"type":"paragraph","content":[{"text":"Most Updates and Consolidations should be applied directly without asking. Only ask the user when:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The right action is genuinely ambiguous (Update vs Replace vs Consolidate vs Delete)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"You are about to Delete a document ","type":"text"},{"text":"and","type":"text","marks":[{"type":"strong"}]},{"text":" the evidence is not unambiguous (see auto-delete criteria in Phase 2). When auto-delete criteria are met, proceed without asking.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"You are about to Consolidate and the choice of canonical doc is not clear-cut","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"You are about to create a successor via Replace","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Question Style","type":"text"}]},{"type":"paragraph","content":[{"text":"Always present choices using the platform's blocking question tool: ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Claude Code (call ","type":"text"},{"text":"ToolSearch","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"select:AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" first if its schema isn't loaded), ","type":"text"},{"text":"request_user_input","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Codex, ","type":"text"},{"text":"ask_user","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Gemini, ","type":"text"},{"text":"ask_user","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Pi (requires the ","type":"text"},{"text":"pi-ask-user","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Question rules:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ask ","type":"text"},{"text":"one question at a time","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prefer ","type":"text"},{"text":"multiple choice","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lead with the ","type":"text"},{"text":"recommended option","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Explain the rationale for the recommendation in one concise sentence","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Avoid asking the user to choose from actions that are not actually plausible","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Focused Scope","type":"text"}]},{"type":"paragraph","content":[{"text":"For a single artifact, present:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"file path","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"2-4 bullets of evidence","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"recommended action","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Then ask:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"text"},"content":[{"text":"This [learning/pattern] looks like a [Keep/Update/Consolidate/Replace/Delete].\n\nWhy: [one-sentence rationale based on the evidence]\n\nWhat would you like to do?\n\n1. [Recommended action]\n2. [Second plausible action]\n3. Skip for now","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not list all five actions unless all five are genuinely plausible.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Batch Scope","type":"text"}]},{"type":"paragraph","content":[{"text":"For several learnings:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Group obvious ","type":"text"},{"text":"Keep","type":"text","marks":[{"type":"strong"}]},{"text":" cases together","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Group obvious ","type":"text"},{"text":"Update","type":"text","marks":[{"type":"strong"}]},{"text":" cases together when the fixes are straightforward","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Present ","type":"text"},{"text":"Consolidate","type":"text","marks":[{"type":"strong"}]},{"text":" cases together when the canonical doc is clear","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Present ","type":"text"},{"text":"Replace","type":"text","marks":[{"type":"strong"}]},{"text":" cases individually or in very small groups","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Present ","type":"text"},{"text":"Delete","type":"text","marks":[{"type":"strong"}]},{"text":" cases individually unless they are strong auto-delete candidates","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Ask for confirmation in stages:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Confirm grouped Keep/Update recommendations","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Then handle Consolidate groups (present the canonical doc and what gets merged)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Then handle Replace one at a time","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Then handle Delete one at a time unless the deletion is unambiguous and safe to auto-apply","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Broad Scope","type":"text"}]},{"type":"paragraph","content":[{"text":"If the user asked for a sweeping refresh, keep the interaction incremental:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Narrow scope first","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Investigate a manageable batch","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Present recommendations","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ask whether to continue to the next batch","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do not front-load the user with a full maintenance queue.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 4: Execute the Chosen Action","type":"text"}]},{"type":"paragraph","content":[{"text":"For each candidate, execute the flow that matches its classification from Phase 2 (confirmed in Phase 3). Read ","type":"text"},{"text":"references/per-action-flows.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and follow the matching section:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep","type":"text","marks":[{"type":"strong"}]},{"text":" — no file edit by default; summarize why the learning remains trustworthy.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update","type":"text","marks":[{"type":"strong"}]},{"text":" — in-place edits when the solution is still substantively correct (path renames, link refreshes, module renames).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Consolidate","type":"text","marks":[{"type":"strong"}]},{"text":" — merge overlapping docs into a canonical doc, delete subsumed docs, update cross-references. The orchestrator handles consolidation directly.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Replace","type":"text","marks":[{"type":"strong"}]},{"text":" — write a successor learning via subagent (passing the documentation contract files), validate frontmatter, then delete the old. When evidence is insufficient, mark stale instead.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Delete","type":"text","marks":[{"type":"strong"}]},{"text":" — final inbound-link check, then remove. Reclassify if late-discovered substantive citations surface.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Only one flow runs per candidate; the reference contains the per-action criteria, examples, and step-by-step instructions.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Output Format","type":"text"}]},{"type":"paragraph","content":[{"text":"The full report MUST be printed as markdown output.","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"After processing the selected scope, output the following report:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"text"},"content":[{"text":"Compound Refresh Summary\n========================\nScanned: N learnings\n\nKept: X\nUpdated: Y\nConsolidated: C\nReplaced: Z\nDeleted: W\nSkipped: V\nMarked stale: S","type":"text"}]},{"type":"paragraph","content":[{"text":"Then for EVERY file processed, list:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The file path","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The classification (Keep/Update/Consolidate/Replace/Delete/Stale)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What evidence was found -- tag any memory-sourced findings with \"(auto memory [claude])\" to distinguish them from codebase-sourced evidence","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What action was taken (or recommended)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For Consolidate: which doc was canonical, what unique content was merged, what was deleted","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For ","type":"text"},{"text":"Keep","type":"text","marks":[{"type":"strong"}]},{"text":" outcomes, list them under a reviewed-without-edits section so the result is visible without creating git churn.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Headless mode report","type":"text"}]},{"type":"paragraph","content":[{"text":"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. ","type":"text"},{"text":"Print the full report. Do not abbreviate, summarize, or skip sections.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Split actions into two sections:","type":"text"}]},{"type":"paragraph","content":[{"text":"Applied","type":"text","marks":[{"type":"strong"}]},{"text":" (writes that succeeded):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For each ","type":"text"},{"text":"Updated","type":"text","marks":[{"type":"strong"}]},{"text":" file: the file path, what references were fixed, and why","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For each ","type":"text"},{"text":"Consolidated","type":"text","marks":[{"type":"strong"}]},{"text":" cluster: the canonical doc, what unique content was merged from each subsumed doc, and the subsumed docs that were deleted","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For each ","type":"text"},{"text":"Replaced","type":"text","marks":[{"type":"strong"}]},{"text":" file: what the old learning recommended vs what the current code does, and the path to the new successor","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For each ","type":"text"},{"text":"Deleted","type":"text","marks":[{"type":"strong"}]},{"text":" file: the file path and why it was removed (problem domain gone, fully redundant, etc.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For each ","type":"text"},{"text":"Marked stale","type":"text","marks":[{"type":"strong"}]},{"text":" file: the file path, what evidence was found, and why it was ambiguous","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Recommended","type":"text","marks":[{"type":"strong"}]},{"text":" (actions that could not be written — e.g., permission denied):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Same detail as above, but framed as recommendations for a human to apply","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Include enough context that the user can apply the change manually or re-run the skill interactively","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Legacy cleanup","type":"text","marks":[{"type":"strong"}]},{"text":" (if ","type":"text"},{"text":"docs/solutions/_archived/","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"List archived files found and recommend disposition: restore (if still relevant), delete (if truly obsolete), or consolidate (if overlapping with active docs)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 5: Commit Changes","type":"text"}]},{"type":"paragraph","content":[{"text":"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).","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Detect git context","type":"text"}]},{"type":"paragraph","content":[{"text":"Before offering options, check:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Which branch is currently checked out (main/master vs feature branch)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Whether the working tree has other uncommitted changes beyond what compound-refresh modified","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recent commit messages to match the repo's commit style","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Headless mode","type":"text"}]},{"type":"paragraph","content":[{"text":"Use sensible defaults — no user to ask:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Context","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Default action","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"On main/master","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Create a branch named for what was refreshed (e.g., ","type":"text"},{"text":"docs/refresh-auth-and-ci-learnings","type":"text","marks":[{"type":"code_inline"}]},{"text":"), commit, attempt to open a PR. If PR creation fails, report the branch name.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"On a feature branch","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Commit as a separate commit on the current branch","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Git operations fail","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Include the recommended git commands in the report and continue","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Stage only the files that compound-refresh modified — not other dirty files in the working tree.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Interactive mode","type":"text"}]},{"type":"paragraph","content":[{"text":"First, run ","type":"text"},{"text":"git branch --show-current","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the current branch is main, master, or the repo's default branch:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create a branch, commit, and open a PR (recommended) — the branch name should be specific to what was refreshed, not generic (e.g., ","type":"text"},{"text":"docs/refresh-auth-learnings","type":"text","marks":[{"type":"code_inline"}]},{"text":" not ","type":"text"},{"text":"docs/compound-refresh","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Commit directly to ","type":"text"},{"text":"{current branch name}","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Don't commit — I'll handle it","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If the current branch is a feature branch, clean working tree:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Commit to ","type":"text"},{"text":"{current branch name}","type":"text","marks":[{"type":"code_inline"}]},{"text":" as a separate commit (recommended)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create a separate branch and commit","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Don't commit","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If the current branch is a feature branch, dirty working tree (other uncommitted changes):","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Commit only the compound-refresh changes to ","type":"text"},{"text":"{current branch name}","type":"text","marks":[{"type":"code_inline"}]},{"text":" (selective staging — other dirty files stay untouched)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Don't commit","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Commit message","type":"text"}]},{"type":"paragraph","content":[{"text":"Write a descriptive commit message that:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Summarizes what was refreshed (e.g., \"update 3 stale learnings, consolidate 2 overlapping docs, delete 1 obsolete doc\")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Follows the repo's existing commit conventions (check recent git log for style)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Is succinct — the details are in the changed files themselves","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Relationship to ce-compound","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ce-compound","type":"text","marks":[{"type":"code_inline"}]},{"text":" captures a newly solved, verified problem","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ce-compound-refresh","type":"text","marks":[{"type":"code_inline"}]},{"text":" maintains older learnings as the codebase evolves — both their individual accuracy and their collective design as a document set","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"Replace","type":"text","marks":[{"type":"strong"}]},{"text":" only when the refresh process has enough real evidence to write a trustworthy successor. When evidence is insufficient, mark as stale and recommend ","type":"text"},{"text":"ce-compound","type":"text","marks":[{"type":"code_inline"}]},{"text":" for when the user next encounters that problem area.","type":"text"}]},{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"Consolidate","type":"text","marks":[{"type":"strong"}]},{"text":" proactively when the document set has grown organically and redundancy has crept in. Every ","type":"text"},{"text":"ce-compound","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Discoverability Check","type":"text"}]},{"type":"paragraph","content":[{"text":"After the refresh report is generated, check whether the project's instruction files would lead an agent to discover and search ","type":"text"},{"text":"docs/solutions/","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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.","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"@","type":"text","marks":[{"type":"code_inline"}]},{"text":"-includes the other (e.g., ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" containing only ","type":"text"},{"text":"@AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", or vice versa). The substantive file is the assessment and edit target; ignore shims. If neither file exists, skip this check entirely.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Assess whether an agent reading the instruction files would learn three things:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"That a searchable knowledge store of documented solutions exists","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Enough about its structure to search effectively (category organization, YAML frontmatter fields like ","type":"text"},{"text":"module","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"tags","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"problem_type","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When to search it (before implementing features, debugging issues, or making decisions in documented areas — learnings may cover bugs, best practices, workflow patterns, or other institutional knowledge)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"docs/solutions/","type":"text","marks":[{"type":"code_inline"}]},{"text":". Use judgment — if an agent would reasonably discover and use the knowledge store after reading the file, the check passes.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the spirit is already met, no action needed.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If not:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"lower-alpha"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Examples of calibration (not templates — adapt to the file):","type":"text"}]},{"type":"paragraph","content":[{"text":"When there's an existing directory listing or architecture section — add a line:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"docs/solutions/ # documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (module, tags, problem_type)","type":"text"}]},{"type":"paragraph","content":[{"text":"When nothing in the file is a natural fit — a small headed section is appropriate:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"## Documented Solutions\n\n`docs/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.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"docs/solutions/","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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: ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Claude Code (call ","type":"text"},{"text":"ToolSearch","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"select:AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" first if its schema isn't loaded), ","type":"text"},{"text":"request_user_input","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Codex, ","type":"text"},{"text":"ask_user","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Gemini, ","type":"text"},{"text":"ask_user","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Pi (requires the ","type":"text"},{"text":"pi-ask-user","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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).","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Amend or create a follow-up commit when the check produces edits.","type":"text","marks":[{"type":"strong"}]},{"text":" If step 4 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., ","type":"text"},{"text":"docs: add docs/solutions/ discoverability to AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":"). 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 edit unstaged alongside the other uncommitted refresh changes — no separate commit logic needed.","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"ce-compound-refresh","author":"@skillopedia","source":{"stars":19041,"repo_name":"compound-engineering-plugin","origin_url":"https://github.com/everyinc/compound-engineering-plugin/blob/HEAD/plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md","repo_owner":"everyinc","body_sha256":"30e73cba0f30967a3d5c2bb0b765c7a65d9573f0d662b7fa25e0a998248bfd3e","cluster_key":"9767166f7d381cb31833a6b048fdbd44ce7e75cc3c1ba8ad6e8c0a02d531b1e2","clean_bundle":{"format":"clean-skill-bundle-v1","source":"everyinc/compound-engineering-plugin/plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md","attachments":[{"id":"8250ce92-858f-5561-bb46-da3b64848c32","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8250ce92-858f-5561-bb46-da3b64848c32/attachment.md","path":"assets/resolution-template.md","size":2448,"sha256":"8f184825c7f9e2a5bd6894e7567776cb4cf19e0c2be1c8c0589ccd73d3f00617","contentType":"text/markdown; charset=utf-8"},{"id":"c4e250c8-b92c-512f-b7c8-15a3de2b28d4","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/c4e250c8-b92c-512f-b7c8-15a3de2b28d4/attachment.md","path":"references/per-action-flows.md","size":6558,"sha256":"7d1ed712d42b8adf7722757c55e0b8d733d4e343bd8c0e8ca93deac57203fc26","contentType":"text/markdown; charset=utf-8"},{"id":"5e47bbfd-306c-5bd8-85a0-4f29ad57e807","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5e47bbfd-306c-5bd8-85a0-4f29ad57e807/attachment.yaml","path":"references/schema.yaml","size":7623,"sha256":"f6d9e2682d9f98742dd12319c05d4715b7d7123d6585a6404deb18c6542c2c24","contentType":"application/yaml; charset=utf-8"},{"id":"d343c690-1fc4-515d-841d-1bc600f5be14","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d343c690-1fc4-515d-841d-1bc600f5be14/attachment.md","path":"references/yaml-schema.md","size":5880,"sha256":"079395c03f6abf89ac95e227ec31b9db13de6bc414ca7fbe0fc72fcbfa1a53d7","contentType":"text/markdown; charset=utf-8"},{"id":"6fabca52-8474-5198-a3b7-8149969c13f9","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6fabca52-8474-5198-a3b7-8149969c13f9/attachment.py","path":"scripts/validate-frontmatter.py","size":5063,"sha256":"c165f67c1885875672d45cd447dc75968589a7bb00982c33140fe925d510cf89","contentType":"text/x-python; charset=utf-8"}],"bundle_sha256":"de3b3727de28c768ecd0230722288855dfcdff2644e87a93674fd2e2330e4553","attachment_count":5,"text_attachments":5,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"security","category_label":"Security"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"security","import_tag":"clean-skills-v1","description":"Refresh stale learning and pattern docs under docs/solutions/ by reviewing them against the current codebase, then updating, consolidating, or deleting drifted ones. Use when the user asks to \"refresh my learnings\", \"audit docs/solutions/\", \"clean up stale learnings\", or \"consolidate overlapping docs\", or when ce-compound flags an older doc as superseded. Do not trigger for general refactor, debugging, or code-review work unless the user has explicitly pointed at docs/solutions/.","argument-hint":"[optional: scope hint — directory, filename, module, or keyword] [mode:headless] "}},"renderedAt":1782980138191}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.