--- name: cf-fix description: > Quick bug fix workflow. Use when the user reports a bug, error, or broken behavior — e.g. "fix this", "it's broken", "not working", "there's a bug", "I'm getting an error", "this crashes", "something is wrong", "why does this fail", "debug this", "it throws", "fix the issue", "resolve this error", "help me fix", "can you fix", "this doesn't work", "stopped working", "regression", "unexpected behavior", "failing test", "broken after update". Also triggers on stack traces, error messages, or descriptions of incorrect program behavior. --- # /cf-fix Fix the bug: **$ARGUMENTS** ## Workflow ### Step 0: Custom Guide Run: `bash "${CLAUDE_PLUGIN_ROOT}/lib/load-custom-guide.sh" cf-fix` If output is not empty, integrate the returned sections into this workflow: - `## Before` → execute before the first step - `## Rules` → apply as additional rules throughout all steps - `## After` → execute after the final step ### Step 1: Understand the Bug 1. Read the error message or bug description from `$ARGUMENTS` 2. If no clear error, **ask the user** to describe the expected vs actual behavior 3. If the bug description is vague, ask: what did you expect? what happened instead? when does it happen? ### Step 2: Verify the Problem Exists 1. Run the failing test or command that triggers the bug 2. Capture the exact error output 3. If you **cannot reproduce**, tell the user and ask for more context — do NOT guess 4. If no test exists AND `--add-tests` flag was used, write one that demonstrates the failure. Otherwise, reproduce by running the code directly or via existing tests. ### Step 3: Recall Past Bugs + Explore Relevant Code **3a. Check existing bug docs** (memory recall): Before exploring, search for related past bugs. Extract 2-3 keywords from the bug description. **Primary — Memory MCP** (if `memory_search` tool is available): Call `memory_search` with: `{ "query": "", "type": "episode", "limit": 3 }` **Fallback — grep** (if memory MCP unavailable): Check `{docsDir}` from `.coding-friend/config.json` (default: `docs`). 1. Grep `^description:` lines across `{docsDir}/memory/bugs/**/*.md` — match against bug keywords 2. If no match, grep `^tags:` lines across `{docsDir}/memory/bugs/**/*.md` If matches found, read the top 1-2 matched files — they may reveal known root causes or patterns. Include any relevant findings as context for the explorer. **3b. Generate task-id and explore relevant code** (via cf-explorer agent): 1. **Generate a task-id**: use format `-` (e.g., `1717500000-fix-auth-race`) 2. **Determine docsDir**: read from `.coding-friend/config.json` if present, default to `docs` 3. **Context file path**: `{docsDir}/context/{task-id}.json` Launch the **cf-explorer agent** to gather context around the bug, passing the context file path so it writes structured findings. Use the **Agent tool** with `subagent_type: "coding-friend:cf-explorer"`. Pass: > Explore the codebase to help diagnose this bug: [bug description from $ARGUMENTS] > > Error output: [from Step 2] > > **Context file:** Write your structured findings to [docsDir/context/.json] > > [If past bug docs were found in 3a]: > Related past bugs found in memory: > [summary of relevant findings] > > Questions to answer: > > 1. What does the code path look like from the error location backward to the origin? > 2. What are the relevant files, functions, and dependencies involved? > 3. Are there existing tests covering this area? > 4. What patterns or conventions might be relevant to the fix? Wait for the cf-explorer to return its findings. ### Step 4: Locate Root Cause Using the cf-explorer's findings: 1. Read the error — full stack trace, not just the message 2. Trace backward from where the error appears to where it originates 3. The bug is usually NOT where the error shows up 4. **State your hypothesis** using this exact template before fixing: > "I believe the root cause is [X] because [evidence]." Name a specific file, function, and line. "A state management issue" is not a hypothesis. "Stale cache in `useUser` at `src/hooks/user.ts:42` because the dependency array is missing `userId`" is a hypothesis. 5. **Rationalization Watch** — if any of these surface, stop and re-examine: | Thought | What it means | Rule | | ----------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------- | | "I'll just try this one thing" | No hypothesis, random-walking | Stop. Write the hypothesis first. | | "Probably the same issue as before" | Treating a new symptom as a known pattern | Re-read the execution path from scratch. | | "One more restart should fix it" | Avoiding the error message | Read the last error verbatim. Never restart more than twice without new evidence. | | "I'm confident it's X" | Confidence is not evidence | Run an instrument that proves it. | ### Step 5: Confirm Approach Before changing code: 1. Tell the user what you believe the root cause is (using the template from Step 4) 2. Explain what you plan to change and why 3. If you're not confident, say so — ask for the user's input 4. **Same symptom after a fix = hard stop.** Do not attempt a second fix until you can state a new hypothesis with new evidence. Escalate immediately to cf-sys-debug if the symptom recurs unchanged. ### Step 6: Implement Fix (via cf-implementer agent) Dispatch the **cf-implementer agent** to fix the bug test-first. Use the **Agent tool** with `subagent_type: "coding-friend:cf-implementer"`. Pass the context file path from Step 3b so the agent can read the explorer's structured findings. **Prompt template:** > Fix the following bug: > > **Bug:** [description from $ARGUMENTS] > **Context file:** [path to docsDir/context/.json] > **Root cause:** [from Step 4] > **Fix approach:** [confirmed in Step 5] > **Failing test/command:** [from Step 2] > **Relevant files:** [paths from explorer findings + root cause analysis in Step 4] > **Test patterns:** [framework, test file locations, run command] > > Requirements: > > 1. If `--add-tests` was passed and no regression test exists for this bug, write one first that demonstrates the failure. Otherwise, skip test writing and fix directly. > 2. Fix the root cause — not the symptom. No try/catch to suppress errors. > 3. One fix at a time — no additional changes > 4. Run the full test suite — no regressions allowed > 5. Report: what was fixed, tests written, and full test output as evidence ### Step 7: Verify Agent Results + Retry on Failure **Parse the last non-empty line** of the cf-implementer's response for the result signal using a strict regex match — `^\[CF-RESULT: (success|failure)( .*)?\]$`: - `[CF-RESULT: success]` → proceed to Step 8 - `[CF-RESULT: failure] ` → trigger retry (see below) - **Sentinel missing, malformed, or not on the last non-empty line → treat as failure** with reason `empty-output`. Never assume silent success — a truncated or aborted agent run may produce output that looks complete but skipped the result signal. **On success:** 1. Review the report — confirm the fix addresses the root cause from Step 4 2. Proceed to Step 8 **Retry protocol** (max 1 retry): 1. **Notify the user** (always visible): ``` > ⟳ Attempt 1 failed (). Retrying with error context... ``` 2. **Update the context file** — read the existing `{docsDir}/context/{task-id}.json`, add the `previous_failure` key, and write it back: ```json { "task_id": "", "task_summary": "", "relevant_files": ["..."], "key_findings": ["..."], "constraints": ["..."], "suggested_approach": "...", "previous_failure": { "reason": "", "error_summary": "", "attempt": 1 } } ``` 3. **Re-dispatch cf-implementer** with the updated context file and an amended prompt: > **RETRY** — Previous attempt failed: [reason]. Error details: [summary]. > Review the context file at [path] for full failure context. > [original prompt from Step 6] 4. **If retry also fails**, escalate to user: ``` > ✗ Both attempts failed. Summary: > - Attempt 1: > - Attempt 2: > Please review and guide the next step. ``` Then fall back to inline fixing following TDD discipline, or load `cf-sys-debug` if the user prefers. 5. **Cleanup**: Delete the context file after the workflow completes (success or escalation) or if the user cancels. ### Step 8: Save Bug Knowledge (conditional) **Only run this step if the fix required more than 1 attempt** (i.e., the first fix attempt in Step 6/7 did not succeed and required re-dispatch or inline fixing). If the fix succeeded on the first attempt, skip to Step 9. 1. Read `language` config (local `.coding-friend/config.json` overrides global, default: `en`) 2. Construct a write spec and delegate to **cf-writer agent** via the **Agent tool** with `subagent_type: "coding-friend:cf-writer"` (use absolute path for `file_path` — use `MAIN_REPO_ROOT` from bootstrap context (fallback: `pwd`), read config from `CF_CONFIG_FILE`, use `CF_DOCS_ROOT` as docs base dir): ``` WRITE SPEC ---------- task: create file_path: {CF_DOCS_ROOT}/memory/bugs/{name}.md language: {language from config} content: | --- title: "" description: "" tags: [tag1, tag2, tag3] created: YYYY-MM-DD updated: YYYY-MM-DD type: episode importance: 3 source: conversation --- # ## Overview ## Root Cause ## Fix ## Prevention ## Related Files - `path/to/file1` - `path/to/file2` readme_update: false auto_commit: false existing_file_action: skip ``` **Frontmatter rules:** - `description`: factual summary for grep recall. Good: `"Race condition in webhook handler causing duplicate payment processing"`. Bad: `"Fixed a bug"`. - `tags`: include error type, affected module, root cause category (e.g., `[race-condition, webhooks, payments]`) ### Step 8b: Index in CF Memory (MANDATORY) **This step is REQUIRED — do NOT skip it.** After the cf-writer saves the bug doc, you MUST call the `memory_store` MCP tool to index it in the database. This is a separate action from writing the file — the cf-writer agent does NOT do this. Call `memory_store` with: - `title`: from the frontmatter title - `description`: from the frontmatter description - `type`: `episode` - `tags`: from the frontmatter tags - `content`: the full markdown content (including frontmatter) - `importance`: 3 (default) - `source`: "auto-capture" - `index_only`: true If the MCP tool is unavailable, log a warning to the user but do NOT fail silently. Show the user a 2-line summary: - **Markdown file:** `{docsDir}/memory/bugs/...md` (created or updated) - **Memory DB:** indexed ✓ — or: MCP unavailable, file only ### Step 9: Auto-Review Automatically invoke `/cf-review` — use the **Skill tool** with skill name `coding-friend:cf-review`. Do NOT ask the user first, just run it. ### Step 10: Performance Suggestion (conditional) If the bug fix involved **performance-critical code** — e.g. database queries, API endpoints, loops over large datasets, memory management, caching, or I/O operations — suggest running `/cf-optimize` on the affected code path. Present it as an optional next step, do NOT auto-run. Example: _"The fix touched a database query path. Want to run `/cf-optimize` on it to verify performance hasn't regressed and look for optimization opportunities?"_ If the fix was not performance-related, skip this step. ## Completion Protocol When the fix is complete (after Step 9/10), report using this format: **On success:** ``` Root cause: [what was wrong, file:line] Fix: [what changed, file:line] Confirmed: [evidence or test that proves the fix] Tests: [pass/fail count, regression test location] ``` Status: **DONE**, **DONE_WITH_CONCERNS** (state caveats), or **BLOCKED** (state what is unknown and what information is needed to proceed). ## Escalation If you've tried **2 fixes** and the bug still persists, before attempting a 3rd fix: 1. **Suggest `/cf-learn`** — Ask the user: _"This bug is taking multiple attempts. Want to run `/cf-learn` to capture the debugging insights so far before continuing?"_ 2. If the user agrees, invoke `/cf-learn` via the **Skill tool** with skill name `coding-friend:cf-learn` 3. Then proceed with the 3rd attempt If you've tried **3 fixes** and the bug persists: 1. Stop fixing 2. Load the `cf-sys-debug` skill 3. Follow its full 4-phase process — the bug is likely deeper than expected ## Quick Checks Before diving deep, try these common causes first: - **Typo in variable/function name?** Check spelling - **Wrong import path?** Check relative vs absolute - **Stale cache/build?** Clean and rebuild - **Missing dependency?** Check package.json/requirements - **Environment mismatch?** Check env vars, node version, etc.