quantumbitcz/forge-fix
skills/forge-fix/SKILL.md
[writes] Fix a bug using root cause investigation and targeted repair. Use when you have a bug report, failing test, error message, ticket ID, or Linear issue to resolve. Trigger: /forge-fix, fix this bug, investigate failure, debug this error, resolve ticket
development
Updated Apr 20, 2026
$ install --global
skillsauthnpx skillsauth add quantumbitcz/dev-pipeline forge-fixInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 20, 2026, 5:16 AM5.5s1 file scanned
SKILL.md
- name:
- forge-fix
- description:
- [writes] Fix a bug using root cause investigation and targeted repair. Use when you have a bug report, failing test, error message, ticket ID, or Linear issue to resolve. Trigger: /forge-fix, fix this bug, investigate failure, debug this error, resolve ticket
- allowed-tools:
- ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep', 'Agent']
/forge-fix — Bugfix Workflow Entry Point
Flags
- --help: print usage and exit 0
- --dry-run: preview actions without writing
Exit codes
See shared/skill-contract.md for the standard exit-code table.
Prerequisites
Before any action, verify:
- Git repository: Run
git rev-parse --show-toplevel 2>/dev/null. If fails: report "Not a git repository. Navigate to a project directory." and STOP. - Forge initialized: Check
.claude/forge.local.mdexists. If not: report "Forge not initialized. Run /forge-init first." and STOP.
What to Expect
After dispatch, fg-100-orchestrator (bugfix mode) will:
- Investigate the bug via fg-020-bug-investigator (max 3 reproduction attempts)
- Write a failing test that demonstrates the bug
- Implement the minimal fix to make the test pass
- Verify no regressions via full test suite
- Create a PR with the fix
Total time: 3-15 minutes. You may be asked to clarify reproduction steps or confirm the root cause.
You are a thin launcher. Your ONLY job is to resolve the bug source and dispatch the forge orchestrator in bugfix mode.
Instructions
1. Input Parsing
Parse $ARGUMENTS to determine the bug source. If no input is provided after stripping flags, ask the user: "What bug should I fix? Provide a ticket ID (e.g., FG-005), --linear <ID>, or a plain bug description."
Supported forms:
/forge-fix {PREFIX}-{NNN}— kanban ticket ID (matches pattern likeFG-005,BUG-012). Resolve title and description from tracking store./forge-fix --linear {ID}— Linear issue ID. Bug description sourced from Linear./forge-fix <plain description>— free-text bug description. A tracking ticket will be created during PREFLIGHT.
Ticket Resolution (kanban):
If the sole argument (or first argument before flags) matches the {PREFIX}-{NNN} pattern:
- Source
shared/tracking/tracking-ops.sh - Call
find_ticket ".forge/tracking" "{ticket_id}"to locate the ticket file - Read the ticket's
titleand## Descriptionsection as the bug description - Pass
ticket_idandticket_file_pathto the orchestrator - If the ticket is not found, warn the user and ask them to provide a bug description directly
Linear Resolution:
If --linear {ID} is provided:
- Set
source=linearandsource_id={ID} - The orchestrator will fetch bug details from Linear during PREFLIGHT
Plain Description:
If input is free text (not a ticket pattern and no --linear flag):
- Set
source=description - The orchestrator will create a tracking ticket during PREFLIGHT if tracking is initialized
2. MCP Detection
Detect available MCPs per shared/mcp-detection.md detection table. For each MCP, check if its probe tool is available. Mark unavailable MCPs as degraded and apply the documented degradation behavior.
Build a comma-separated list of detected integrations (e.g., Linear, Playwright). If none detected, use none.
3. Dispatch Orchestrator
Use the Agent tool to invoke fg-100-orchestrator with the following prompt:
Execute the bugfix workflow for:
{bug_description}Mode: bugfix
Bug source:
{source}(one of: kanban, linear, description)Source ID:
{source_id}(omit if source=description)Ticket file:
{ticket_file_path}(include only if source=kanban and ticket was resolved)Available MCPs:
{detected_mcps}
Where {bug_description} is the resolved bug text (from ticket title+description if kanban, otherwise raw user input), and {detected_mcps} is the list from step 2.
4. Relay Output
When the orchestrator completes, relay its final output (PR URL, escalation, or abort message) back to the user unchanged. Do not add commentary or interpretation.
5. Forbidden Actions
- Do NOT investigate the bug yourself
- Do NOT write or modify any code or tests
- Do NOT create tracking tickets manually (the orchestrator does this during PREFLIGHT)
- Do NOT fetch Linear issues directly (the orchestrator handles Linear integration)
- Do NOT make any decisions about the fix approach
Error Handling
| Condition | Action |
|-----------|--------|
| Prerequisites fail | Report specific error message and STOP |
| Empty input (no bug description or ticket ID) | Ask user for bug description or ticket ID before dispatching |
| Kanban ticket not found | Warn user and ask for bug description directly |
| Linear issue fetch fails | Fall back to description-based mode. Log WARNING about Linear unavailability |
| Orchestrator dispatch fails | Report "Bugfix orchestrator failed to start. Check plugin installation." and STOP |
| Orchestrator returns error | Relay the error unchanged. Suggest /forge-recover diagnose for state issues |
| State corruption | Suggest /forge-recover repair to fix state, then retry |
See Also
/forge-run-- Full pipeline entry point (usebugfix:prefix for quick bugfix routing)/forge-recover diagnose-- Diagnose pipeline health if the bugfix run fails/forge-shape-- Shape a complex bug investigation into a structured spec first/forge-recover resume-- Resume an aborted bugfix run from its last checkpoint
Related Skills
quantumbitcz/forge
development
VerifiedTrustedCommunity
[writes] Build, fix, deploy, review, or modify code in this project. Universal entry for the forge pipeline. Auto-bootstraps on first run; brainstorms before planning when given a feature description. Use when you want to take any productive action: implementing features, fixing bugs, reviewing branches, deploying, committing, running migrations.
SKILL.mdUpdated Apr 30, 2026
quantumbitcz/forge-admin
tools
VerifiedTrustedCommunity
[writes] Manage forge state and configuration: recovery, abort, config edits, session handoff, automations, playbooks, output compression, knowledge graph maintenance. Use when you need to recover from broken pipeline state, edit settings, or manage long-lived state.
SKILL.mdUpdated Apr 30, 2026
quantumbitcz/forge-handoff
development
VerifiedTrustedCommunity
[writes] Create, list, show, resume, or search forge session handoffs. Use when context is getting heavy and you want to transfer a forge run or conversation into a fresh Claude Code session, or to resume from a prior handoff artefact. Subcommands - no args (write), list, show, resume, search.
SKILL.mdUpdated Apr 23, 2026
quantumbitcz/forge-graph
development
VerifiedTrustedCommunity
[writes] Manage the Neo4j knowledge graph. Subcommands: init, rebuild (writes); status, query <cypher>, debug (read-only). Requires Docker. No default — an explicit subcommand is required. Use when setting up the graph for the first time, rebuilding after major refactors, checking graph health, or running ad-hoc Cypher diagnostics.
SKILL.mdUpdated Apr 21, 2026