diff --git a/plugins/compound-engineering/skills/ce-compound/SKILL.md b/plugins/compound-engineering/skills/ce-compound/SKILL.md index 9809d8aa7..bd8fc455e 100644 --- a/plugins/compound-engineering/skills/ce-compound/SKILL.md +++ b/plugins/compound-engineering/skills/ce-compound/SKILL.md @@ -1,6 +1,7 @@ --- name: ce-compound description: Document a recently solved problem to compound your team's knowledge +argument-hint: "[mode:autofix] [depth:lightweight|standard|deep] [brief context]" --- # /ce-compound @@ -30,12 +31,42 @@ These files are the durable contract for the workflow. Read them on-demand at th When spawning subagents, pass the relevant file contents into the task prompt so they have the contract without needing cross-skill paths. +## Mode Detection + +Parse `$ARGUMENTS` for `mode:autofix`. If present, also parse an optional `depth:` token. Strip matched tokens; the remainder is the context hint. + +| Mode | When | Behavior | +|------|------|----------| +| **Interactive** (default) | No `mode:autofix` token | User picks Standard or Lightweight at the Execution Strategy prompt; all documented interactive prompts run. | +| **Autofix** | `mode:autofix` in arguments | No user interaction. Execution path and session-history default resolve from `depth:` (default `lightweight`). | + +**Depth presets** (autofix mode only): + +- `depth:lightweight` (default) — Lightweight Mode: single-pass, no subagents, no overlap check. +- `depth:standard` — Standard Mode: Phase 1 parallel research, overlap-update, Phase 3 specialized reviewers. Session history off. +- `depth:deep` — Standard Mode + session history on. + +In autofix mode, invalid `depth:` values halt before subagent dispatch and emit `ce-compound failed. Reason: unknown depth:. Valid values: lightweight, standard, deep.` + +### Autofix mode rules + +- **Skip all user questions.** Never pause — the mode-selection prompt, Phase 2.5 selective-refresh prompt (multi-candidate case), session-history opt-in, Discoverability Check consent, and "What's next?" menu are all suppressed. +- **Do not edit instruction files.** Surface the Discoverability gap as a `Discoverability recommendation` line in the output; do not modify AGENTS.md / CLAUDE.md. +- **Be conservative about writing.** Respect the advisory Preconditions (`problem_solved`, `solution_verified`, `non_trivial`). If the conversation and context hint do not evidence a substantive, verified fix, emit the no-op autofix output explaining what was missing. +- **Always print the full output block** — do not abbreviate, summarize, or skip sections. + ## Execution Strategy +**Autofix mode:** Skip this entire section. +- `depth:lightweight` (default when `depth:` is absent) → jump directly to the Lightweight Mode execution path below. +- `depth:standard` or `depth:deep` → execute Standard Mode below with the interactive prompts guarded per the Mode Detection section. + +**Interactive mode** (default): + Present the user with two options before proceeding, using the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. ``` -1. Full (recommended) — the complete compound workflow. Researches, +1. Standard (recommended) — the complete compound workflow. Researches, cross-references, and reviews your solution to produce documentation that compounds your team's knowledge. @@ -47,7 +78,7 @@ Present the user with two options before proceeding, using the platform's blocki Do NOT pre-select a mode. Do NOT skip this prompt. Wait for the user's choice before proceeding. -**If the user chooses Full**, ask one follow-up question before proceeding. Detect which harness is running (Claude Code, Codex, or Cursor) and ask: +**If the user chooses Standard**, ask one follow-up question before proceeding. Detect which harness is running (Claude Code, Codex, or Cursor) and ask: ``` Would you also like to search your [harness name] session history @@ -55,16 +86,18 @@ for relevant knowledge to help the Compound process? This adds time and token usage. ``` -If the user says yes, dispatch the Session Historian in Phase 1. If no, skip it. Do not ask this in lightweight mode. +If the user says yes, dispatch the Session Historian in Phase 1. If no, skip it. Do not ask this in lightweight mode or in autofix mode — `mode:autofix` with `depth:deep` dispatches the Session Historian without asking; all other autofix paths skip it (see Mode Detection). --- -### Full Mode +### Standard Mode + +Used by Interactive mode when the user picks Standard, and by `mode:autofix depth:standard|deep` with interactive prompts guarded per Mode Detection. **The primary output is ONE file - the final documentation.** -Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator writes files: the solution doc in Phase 2, and — if the Discoverability Check finds a gap — a small edit to a project instruction file (AGENTS.md or CLAUDE.md). The instruction-file edit is maintenance, not a second deliverable; it ensures future agents can discover the knowledge store. +Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator writes files: the solution doc in Phase 2, and — if the Discoverability Check finds a gap and the run is in Standard interactive mode — a small edit to a project instruction file (AGENTS.md or CLAUDE.md). In autofix mode the instruction-file edit is never written; the gap is surfaced as a Discoverability recommendation in the output instead. ### Phase 0.5: Auto Memory Scan @@ -166,8 +199,8 @@ Launch research subagents. Each returns text data to the orchestrator. -#### 4. **Session Historian** (foreground, after launching the above — only if the user opted in) - - **Skip entirely** if the user declined session history in the follow-up question +#### 4. **Session Historian** (foreground, after launching the above) + - Dispatch if the user opted in during the follow-up question, or if `mode:autofix depth:deep` was passed. Otherwise skip. - Dispatched as `ce-session-historian` - Dispatch in **foreground** — this agent reads session files outside the working directory (`~/.claude/projects/`, `~/.codex/sessions/`, `~/.cursor/projects/`) which background agents may not have access to - Searches prior Claude Code, Codex, and Cursor sessions for the same project to find related investigation context @@ -249,7 +282,7 @@ It does **not** make sense to invoke `ce-compound-refresh` when: Use these rules: - If there is **one obvious stale candidate**, invoke `ce-compound-refresh` with a narrow scope hint after the new learning is written -- If there are **multiple candidates in the same area**, ask the user whether to run a targeted refresh for that module, category, or pattern set +- If there are **multiple candidates in the same area**, ask the user whether to run a targeted refresh for that module, category, or pattern set. In autofix mode, do not ask — recommend `ce-compound-refresh` via the `Follow-up` line in the output with the broadest useful scope (module, category, or pattern set) and move on. - If context is already tight or you are in lightweight mode, do not expand into a broad refresh automatically; instead recommend `ce-compound-refresh` as the next step with a scope hint When invoking or recommending `ce-compound-refresh`, be explicit about the argument to pass. Prefer the narrowest useful scope: @@ -304,7 +337,7 @@ After the learning is written and the refresh decision is made, check whether th `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. ``` - c. In full 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 `docs/solutions/` unless the instruction file surfaces it. Show the proposed change and where it would go, then use the platform's blocking question tool to get consent before making the edit: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting the proposal in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. In lightweight mode, output a one-liner note and move on + c. In Standard 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 `docs/solutions/` unless the instruction file surfaces it. Show the proposed change and where it would go, then use the platform's blocking question tool to get consent before making the edit: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting the proposal in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. In lightweight mode, output a one-liner note and move on. In autofix mode, include it as a `Discoverability recommendation` line in the output — do not attempt to edit instruction files (autofix scope is doc capture, not project config). ### Phase 3: Optional Enhancement @@ -333,6 +366,8 @@ Based on problem type, optionally invoke specialized agents to review the docume **Single-pass alternative — same documentation, fewer tokens.** This mode skips parallel subagents entirely. The orchestrator performs all work in a single pass, producing the same solution document without cross-referencing or duplicate detection. + +**This path is also the execution target for `mode:autofix depth:lightweight`** (see Mode Detection). Autofix adds no-prompt guardrails on top of Lightweight — the execution steps below are identical, but autofix uses a dedicated output block (see **Autofix mode output** under Success Output) so callers can parse the result programmatically. `mode:autofix depth:standard|deep` uses the Standard Mode execution path instead, not this one. The orchestrator (main conversation) performs ALL of the following in one sequential pass: @@ -460,7 +495,68 @@ What's next? 5. Other ``` -**After displaying the success output, present the "What's next?" options using the platform's blocking question tool:** `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. Do not continue the workflow or end the turn without the user's selection. +**After displaying the success output, present the "What's next?" options using the platform's blocking question tool:** `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. Do not continue the workflow or end the turn without the user's selection. In autofix mode, skip this step. + +### Autofix mode output + +**Success** — a new doc was written, or (only on `depth:standard|deep` overlap-high) an existing doc was updated: + +``` +✓ Documentation complete (mode:autofix) + +Depth: [lightweight|standard|deep] + +File created: +- docs/solutions/[category]/[filename].md + +Track: [bug|knowledge] +Category: [category]/ + +[When an existing doc was updated instead (only on depth:standard|deep, overlap high), + replace the first line with "✓ Documentation updated (mode:autofix)" and replace the + "File created:" block above with:] +Overlap detected: docs/solutions/[category]/[existing-filename].md + Matched dimensions: [problem statement, root cause, solution, referenced files, prevention] +File updated: +- docs/solutions/[category]/[existing-filename].md (added last_updated: YYYY-MM-DD) + +[If depth:standard or depth:deep:] +Phase 1 subagents: + - Context Analyzer: [one-line summary] + - Solution Extractor: [one-line summary] + - Related Docs Finder: overlap=[low|moderate|none|high], refresh_candidates=[count] + - Session Historian: [off (depth:standard) | one-line summary (depth:deep)] + +Phase 3 specialized reviewers: + - [each agent invoked and its one-line verdict, or "none applicable"] + +[If Phase 2.5 flagged a refresh candidate:] +Refresh candidate: docs/solutions/[path/to/stale-or-overlapping-doc].md + Reason: [one-line rationale] + Follow-up: /ce-compound-refresh mode:autofix [scope hint] + +[If discoverability check found instruction files don't surface the knowledge store:] +Discoverability recommendation: AGENTS.md/CLAUDE.md does not surface docs/solutions/ + Suggested addition: [one-liner or small section — do NOT apply the edit in autofix mode] +``` + +**No-op** — preconditions not met (trivial fix, unverified solution, or nothing substantive in context): + +``` +✓ No documentation written (mode:autofix) + +Depth: [lightweight|standard|deep] + +Reason: [which precondition failed — e.g., "non_trivial check: change was a one-character typo" + or "solution_verified: no verification evidence in conversation or context hint" + or "problem_solved: solution still in progress"] + +Context considered: +- [one-line summary of what was available — e.g., "brief context hint: ''", + "recent commits on branch: 3", "conversation history: empty"] + +No action required. A human can invoke /ce-compound interactively if this was a misjudgment. +``` **Alternate output (when updating an existing doc due to high overlap):** diff --git a/plugins/compound-engineering/skills/ce-compound/references/autofix-output-parse-contract.md b/plugins/compound-engineering/skills/ce-compound/references/autofix-output-parse-contract.md new file mode 100644 index 000000000..0187b0ab4 --- /dev/null +++ b/plugins/compound-engineering/skills/ce-compound/references/autofix-output-parse-contract.md @@ -0,0 +1,39 @@ +# Autofix output parse contract + +Audience: downstream parsers (orchestrators, post-merge hooks, CI steps) that invoke `/ce-compound mode:autofix ...` and parse the output programmatically. + +This file is not loaded by the skill at runtime. It documents what callers can rely on. + +## Reliable anchors + +Search anywhere in stdout — first-line discipline does not hold; the agent prepends narration before any template block. + +**Shape detector substrings.** Presence of either substring identifies which output shape was emitted: + +- `✓ Documentation complete` — success-complete shape (substring; the `(mode:autofix)` suffix is unreliable on this line, see best-effort) +- `✓ No documentation written (mode:autofix)` — no-op shape + +When the no-op substring is present, the no-op block follows it in the same response with these anchors on their own lines: + +- `Depth: [lightweight|standard|deep]` +- `Reason: ` +- `Context considered:` followed by bulleted summary lines + +## Best-effort fields + +Callers MUST NOT hard-fail when these are absent. They are emitted opportunistically and frequently drop in headless runs: + +- `✓ Documentation updated` substring — success-updated path is unreachable in `claude -p` (overlap-update requires the Solution Extractor to read conversation history); demoted by construction +- `(mode:autofix)` suffix on success-shape lines (lightweight mode emits its own suffix variants) +- `File created:` / `File updated:` paths +- `Track:` / `Category:` / `Overlap detected:` fields +- `Refresh candidate:` and `Discoverability recommendation:` blocks +- `Phase 1 subagents:` / `Phase 3 specialized reviewers:` blocks (template-only; never observed in headless runs) + +## Invalid-argument error + +If the caller passes an unknown `depth:` value with `mode:autofix`, the skill halts before subagent dispatch and emits: + +``` +ce-compound failed. Reason: unknown depth:. Valid values: lightweight, standard, deep. +```