| name | fix |
| description | Debug and fix bugs with interactive upstream trace-back — diagnoses root cause level, confirms upstream document updates, and applies TDD fixes. Supports --repos flag for parallel bug fixing across multiple repositories.
|
Code Forge — Fix
⚡ Execution Entry Point
@../shared/execution-entrypoint.md
For this skill: start at Step 0.1 (Multi-Repo Detection), then Step 0.5. If you catch yourself about to say "falling back to manual fix", STOP and go to the indicated step.
Systematically debug and fix bugs with interactive trace-back to upstream documents (task descriptions, plans, requirements).
When to Use
- Encountered a bug or unexpected behavior in a feature
- Need to diagnose whether the root cause is in code, task description, plan, or requirements
- Want to fix the bug with TDD and keep upstream documents in sync
- Multi-repo: Same bug manifests across multiple language repos (e.g., Python + TypeScript + Rust)
Examples
/code-forge:fix login page returns 500 error
/code-forge:fix @issues/bug-123.md
/code-forge:fix --review user-auth
/code-forge:fix --review
/code-forge:fix "connection pool exhaustion" --repos ~/api-python ~/api-typescript ~/api-rust
Workflow
Bug Input → Context Scan → Feature Association → Root Cause → Trace-back → TDD Fix → Doc Sync → Summary
Detailed Steps
@../shared/configuration.md
Step 0.1: Detect Multi-Repo Mode
If $ARGUMENTS does not contain --repos, skip this step and continue below.
Note: --review and --repos cannot be combined. If both are present, show error: "Cannot combine --review with --repos. Review reports are per-repo — run /code-forge:fix --review in each repo separately."
If --repos is present (without --review): first, resolve <cf_scripts> per Locating the script layer (the configuration step). The code-forge install directory <cf_install> is its grandparent (<cf_scripts>/../.. — the folder that contains skills/); this is the install, not the user's project. Then dispatch Agent(subagent_type="general-purpose", description="Fix --repos coordinator") with prompt containing the resolved absolute paths:
Read these two files and follow them exactly:
<cf_install>/skills/shared/multi-repo.md — the protocol steps MR-1~MR-5<cf_install>/skills/fix/multi-repo-defs.md — the fix-specific definitions
User arguments: $ARGUMENTS
Then stop — do not continue to Step 0.5.
Step 0.5: Project Analysis
Before diagnosing, understand the project's architecture and tech stack:
@../shared/project-analysis.md
Execute PA.1 (Project Profile) and PA.2 (Architecture Analysis). This context determines:
- WHERE to look for the bug (which layers, which modules)
- HOW errors propagate (call graph, data flow)
- WHAT language-specific patterns to check (Rust ownership issues, Go error chains, Python import cycles, etc.)
Step 1: Receive Bug Description
Accept input in three modes:
- Prompt text (e.g.,
/code-forge:fix login page returns 500 error) — use the text as bug description
- File reference (e.g.,
/code-forge:fix @issues/bug-123.md) — read the file for bug details
- Review mode (
/code-forge:fix --review [feature-name]) — read the review report and batch-fix all issues. See Step 1R below.
1.0 Path-Like Input Guard
Before treating input as prompt text, check if it looks like a file/directory path without @. If the input does NOT start with @ and is NOT --review, but matches ANY of these patterns, it is likely a path the user forgot to prefix with @:
- Contains
/ (e.g., issues/bug-123.md, ../bugs/report.md)
- Starts with
. (e.g., ./bug-report.md)
- Ends with
.md (e.g., bug-123.md)
- Matches an existing file or directory on disk
Action: Use AskUserQuestion:
Your input looks like a file path: "{input}"
Did you mean to use file mode? (file paths require an @ prefix)
- Options:
- "Yes, use as file path" → prepend
@ and treat as file reference
- "No, treat as bug description" → continue as prompt text
If no input provided, use AskUserQuestion to ask: "Describe the bug you encountered."
For prompt text and file reference modes, store the bug description and continue to Step 2.
For --review mode, go to Step 1R.
Step 1R: Review Mode Setup
Locate and parse the review report. The review report lives in the current conversation context (displayed by a prior /code-forge:review run). A saved file on disk is the fallback.
Source priority:
-
Conversation context (primary): Look for the most recent review report output in the current conversation. The report starts with # Code Review: or # Project Review: and contains the structured dimension sections. If found, use it directly.
-
Saved file (fallback): Only if no review report exists in the current conversation:
- With feature name (
--review my-feature): read {output_dir}/{feature_name}/review.md
- Without feature name (
--review): search {output_dir}/project-review.md first, then scan {output_dir}/*/review.md
- If multiple found: use
AskUserQuestion to let user select
-
Neither found: Show error — "No review report found in this session. Run /code-forge:review first, or /code-forge:review --save to persist to disk."
-
Parse issues from the report:
- Extract all issues with severity
blocker, critical, and warning
- Skip
suggestion-level issues (these are optional improvements, not bugs)
- Group issues by file for efficient fixing
- Sort by severity: blockers first, then criticals, then warnings
-
Present issue summary and confirm:
Display:
Review Report: {feature_name or "project"}
Found {N} issues to fix:
Blockers: {count}
Criticals: {count}
Warnings: {count}
Issues:
1. [{severity}] {file}:{line} — {title}
2. [{severity}] {file}:{line} — {title}
...
Use AskUserQuestion: "Fix all {N} issues? Or enter issue numbers to fix selectively (e.g., 1,3,5)."
- "all" / "yes" → process all issues
- Comma-separated numbers → process only selected issues
- "cancel" → abort
-
Batch execution:
For each selected issue (or group of issues in the same file):
-
Update state.json (if associated with a feature):
Add a single aggregated fix record to the fixes array:
{
"bug": "review fixes — {N} issues",
"root_cause_level": 1,
"root_cause": "Code-level issues identified by review",
"fixed_files": ["path/to/file1.ext", "path/to/file2.ext"],
"commits": ["abc1234", "def5678"],
"doc_updates": [],
"fixed_at": "ISO timestamp"
}
-
Display batch summary:
Review Fixes Complete: {feature_name or "project"}
Fixed: {fixed_count}/{total_count} issues
Blockers: {fixed_blockers}/{total_blockers}
Criticals: {fixed_criticals}/{total_criticals}
Warnings: {fixed_warnings}/{total_warnings}
{If any failed:}
⚠ Could not fix:
- {title} ({file}:{line}) — {reason}
Commits:
{commit hashes}
Next steps:
/code-forge:review {feature_name} Re-run review to verify fixes
/code-forge:status {feature_name} View updated progress
Review mode ends here — do NOT continue to Step 2.
Step 2: Project Context Scan
Scan the project codebase to understand the context:
- Use
Glob to get project structure overview
- Use
Grep to search for keywords from the bug description in the codebase
- Identify files and modules likely related to the bug
- Note the tech stack and testing framework used
Store a concise context summary (~500 words).
Step 3: Associate Feature (If Exists)
Attempt to associate the bug with an existing code-forge feature:
- Search both
{output_dir}/*/state.json and .code-forge/tmp/*/state.json for all features
- For each feature, check if the bug-related files overlap with the feature's task files (read
tasks/*.md → "Files Involved" sections)
- Match found → load the feature's
plan.md and relevant tasks/*.md as additional context. Note the feature name.
- No match found → mark as standalone bug. Skip upstream trace-back (Steps 5 and 7). Proceed with code-only fix.
If multiple features match, use AskUserQuestion to let user select the most relevant one.
Step 4: Root Cause Diagnosis
Offload to sub-agent for deep analysis.
Spawn an Agent tool call with:
subagent_type: "general-purpose"description: "Diagnose bug root cause"
Sub-agent prompt must include:
- Bug description
- Project context summary from Step 2
- Feature context (plan.md, task files) if associated in Step 3
- Instruction to: reproduce the bug, identify the root cause, classify the root cause level
Root cause levels:
| Level | Description | Example |
|---|
| 1 | Code bug | Logic error, boundary miss, typo, wrong variable |
| 2 | Incomplete task description | Task.md steps missing a case, wrong acceptance criteria |
| 3 | Plan design flaw | Architecture doesn't handle a scenario, missing component |
| 4 | Incomplete requirement doc | Original feature doc missing a requirement |
Sub-agent must return:
ROOT_CAUSE_LEVEL: <1-4>
ROOT_CAUSE_SUMMARY: <1-2 sentence description>
AFFECTED_FILES:
- path/to/file.ext: <what's wrong>
UPSTREAM_DOCS_AFFECTED: (only if Level >= 2)
- Level 2: tasks/<task>.md — <what's missing/wrong>
- Level 3: plan.md — <what's missing/wrong>
- Level 4: {input_dir}/<feature>.md — <what's missing/wrong>
PROPOSED_FIX: <brief fix description>
REGRESSION_TEST: <what test to write>
Step 5: Interactive Trace-back Confirmation
This step only runs if Level >= 2 AND the bug is associated with a feature.
Present the root cause analysis to the user, then confirm upstream updates level by level.
5.1 Present Analysis
Display:
Root Cause Analysis
Level: {level} — {level_description}
Summary: {root_cause_summary}
Affected code:
{affected_files list}
Upstream documents affected:
{upstream_docs_affected list}
5.2 Per-Level Confirmation
For each affected upstream level (from lowest to highest), use AskUserQuestion:
"Root cause traced to {level_name}: {doc_path} — {what's wrong}. Update this document?"
Options:
- "Yes, update this document" → mark for update in Step 7
- "No, code fix only" → skip this level, do not modify this document
- "Show proposed changes" → display the proposed diff for this document, then re-ask
5.3 Generate Fix Plan
Compile the fix plan:
- Code changes to make (always)
- Upstream documents to update (based on user confirmations)
- Regression test to write
Step 6: TDD Fix
Execute the fix following TDD methodology.
Mandatory before 6.1: Apply the design-first discipline. Bug fixes are the most common site of patch-soup development — adding a special case to compensate for buggy logic, instead of fixing the underlying logic, is the textbook "bug-fix epicycle" anti-pattern. Read the affected subsystem fully, understand why the bug exists, and determine whether the right fix is a localized correction or a small refactor of the surrounding code. Do not add an if special_case: branch when the underlying logic is wrong — fix the logic. Public interfaces remain stable throughout. The full discipline:
@../shared/design-first.md
6.1 Write Regression Test
Write a test that reproduces the bug:
- Test must FAIL with the current code (proving the bug exists)
- Test must describe the expected correct behavior
Run the test to verify it fails.
6.2 Implement Fix
Make the minimal code changes to fix the bug — but "minimal" means "minimal correct", not "minimal lines". A two-line patch that papers over a broken function is worse than a ten-line refactor that fixes the function. If the design-first checklist (above) revealed that the bug stems from a structural issue, fix the structure rather than adding compensating code around it. If you choose a localized patch over a refactor, briefly note in the commit message why the refactor was deferred so future-you can revisit.
Run the regression test to verify it passes.
6.3 Run Full Test Suite
Run the project's full test suite to ensure no regressions:
- If tests pass: continue
- If tests fail: investigate and fix before proceeding
6.4 Commit Fix
Commit the code changes with a descriptive message:
fix: {brief description of bug fix}
Step 7: Upstream Document Sync
This step only runs if upstream documents were confirmed for update in Step 5.
For each confirmed document update:
7.1 Show Diff Preview
Before modifying each document, show the proposed changes in diff format:
--- a/{doc_path}
+++ b/{doc_path}
@@ ... @@
- old content
+ new content
Ask user: "Apply this change?" (Yes / No / Edit manually)
7.2 Apply Changes
- Level 2 (task.md): Update the task's steps, acceptance criteria, or files involved
- Level 3 (plan.md): Update architecture, task breakdown, or risk sections
- Level 4 (feature doc): Update requirements or scope
7.3 Commit Document Updates
Commit upstream document changes separately from code fix:
docs: update {doc_path} — traced from bug fix
Step 8: Update state.json
If the bug is associated with a feature:
- Read the feature's
state.json
- Add a
fixes array (if not present) to the feature-level metadata
- Append a fix record:
{
"bug": "brief bug description",
"root_cause_level": 2,
"root_cause": "brief root cause",
"fixed_files": ["path/to/file.ext"],
"commits": ["abc1234"],
"doc_updates": ["tasks/auth-logic.md"],
"fixed_at": "ISO timestamp"
}
- Update
state.json updated timestamp
If standalone bug (no associated feature): skip this step.
Step 9: Summary
Display fix summary:
Bug Fix Complete
Bug: {description}
Root Cause: Level {level} — {summary}
Code Changes:
{files changed}
Regression Test:
{test file and name}
Document Updates:
{list of updated docs, or "none"}
Commits:
{commit hashes}
Next steps:
/code-forge:status {feature} View updated progress
/code-forge:review {feature} Review all changes
