npx claudepluginhub suriyel/longtaskforagent --plugin long-taskThis skill uses the workspace's default tool permissions.
<EXTREMELY-IMPORTANT>
Executes step-by-step bug fix workflow: read issue, diagnose root cause, reproduce (browser for UI bugs), minimal fix, regression test, verify, open PR.
Fixes bugs via root cause diagnosis with debugger/gap-analyzer, requirements.md generation, /execute delegation, 3-retry circuit breaker, and QA.
Provides phased workflow for bug fixes: root cause analysis, minimal implementation, code review, regression testing, security checks, validation, documentation, and deployment. Use for bugs, issues, errors.
Share bugs, ideas, or general feedback.
Your job is ONLY: validate → reproduce → root cause → enqueue → chain to Worker. The actual fix (TDD, quality gates, ST, review) is handled by the Worker pipeline — do NOT implement fixes here.
Print: "I'm using the long-task-hotfix skill. Processing bugfix-request.json."
Use TodoWrite to track your progress through the 8 steps.
Run:
python scripts/validate_bugfix_request.py bugfix-request.json
If validation fails:
AskUserQuestion asking the user to fix the fileRead these files in order:
bugfix-request.json — understand title, description, severity, feature_id, reproduction stepsfeature-list.json — find the linked feature (if feature_id non-null), read tech_stack, quality_gates; determine next available feature idlong-task-guide.md — environment activation commandsenv-guide.md (if exists) — service start/stop commandstask-progress.md ## Current State section — recent session historygit log --oneline -10 — recent commit contextIf feature_id is non-null: read the linked feature's entry from feature-list.json to understand context (its ui field, existing srs_trace, st_case_path).
Goal: Confirm the bug is reproducible before any analysis.
long-task-guide.mdenv-guide.md or long-task-guide.md): start them using env-guide.md Start commands; capture first 30 lines of startup output; record PIDs in task-progress.mdreproduction_steps from bugfix-request.json exactlyHARD GATE — Cannot Reproduce: If the bug cannot be reproduced:
task-progress.mdenv-guide.md Stop commands)bugfix-request.jsonAskUserQuestion asking for clarification (more detailed steps, specific environment, sample data)Execute the 4-phase systematic debugging process from skills/long-task-work/references/systematic-debugging.md:
Phase 1 — Root Cause Investigation: collect full error evidence, find minimal reproduction, check recent git changes, trace data flow from entry point to failure.
Phase 2 — Pattern Analysis: find similar working code paths, compare contexts, check dependency versions and config values.
Phase 3 — Hypothesis & Testing: form ONE specific testable hypothesis; make ONE minimal diagnostic change to confirm or disprove it; if wrong, return to Phase 1.
Phase 4 — Confirmed Root Cause: arrive at a single confirmed root cause statement.
Required output: "Root cause: [one-sentence statement]"
Iron Law: NO FEATURE ENTRY before root cause is confirmed. If you cannot confirm root cause after 3 Phase 3 iterations, AskUserQuestion to ask the user for more context.
Add a new feature entry to feature-list.json. Determine the next available id (max existing id + 1).
New feature object:
{
"id": <next available>,
"wave": <current max wave id>,
"category": "bugfix",
"title": "Fix: <title from bugfix-request.json>",
"description": "<actual_behavior from bugfix-request.json> — Root cause: <confirmed root cause>",
"priority": "<Critical|Major → 'high', Minor → 'medium', Cosmetic → 'low'>",
"status": "failing",
"srs_trace": ["<FR-xxx from linked feature, or new FR-xxx if unlinked>"],
"dependencies": [<fixed_feature_id>],
"ui": <copy from linked feature's ui field, or false if feature_id is null>,
"deprecated": false,
"deprecated_reason": null,
"supersedes": null,
"bug_severity": "<severity from bugfix-request.json>",
"bug_source": "manual-testing",
"fixed_feature_id": <feature_id from bugfix-request.json, or null>,
"root_cause": "<confirmed root cause one-sentence>"
}
Notes:
dependencies: set to [fixed_feature_id] if non-null (ensures Worker processes the original feature before this fix); set to [] if nullui: if feature_id is non-null, use the linked feature's ui field; otherwise falsewave: use the current maximum wave id from feature-list.json's waves arrayfixed_feature_id is non-null and ATS doc exists (docs/plans/*-ats.md), look up the linked feature's requirement in the ATS mapping table. Set srs_trace to include the linked feature's requirement IDs so downstream feature-st can derive the required test cases from SRS acceptance criteriaAfter adding, validate:
python scripts/validate_features.py feature-list.json
Fix any validation errors before continuing.
Append a hotfix session entry after the current ## Current State content:
## Hotfix Session — YYYY-MM-DD: <bug title>
- **Severity**: <severity>
- **Bugfix Feature ID**: #<new id>
- **Fixed Feature**: #<fixed_feature_id> <feature title> (or "Unlinked")
- **Root Cause**: <one sentence>
- **Status**: Enqueued — Worker will handle TDD/Quality/ST/Review
Also update the ## Current State header to reflect the new failing feature.
env-guide.md Stop commands; verify stoppedbugfix-request.json (this is the final irreversible action — only after Steps 6 and 7 are complete and validate_features.py has passed)Bug #<id> enqueued as category=bugfix feature.
Title: Fix: <title>
Severity: <severity>
Root cause: <one sentence>
Worker will handle: TDD → Quality → ST → Review
long-task:long-task-workvalidate_features.py must pass firstbugfix-request.json AND increment-request.json exist: process this hotfix fully first; do NOT delete increment-request.json; it will be processed in the next sessionThese thoughts mean STOP — you're rationalizing:
| Thought | Reality |
|---|---|
| "I can see the bug in the code, let me just fix it" | Root cause 4-phase first; then enqueue; Worker fixes |
| "I know the root cause, skipping Phase 1-3" | All 4 phases are mandatory; documenting them protects against wrong assumptions |
| "Can't reproduce but I know the cause" | Cannot Reproduce = stop; document in task-progress.md; ask user |
| "I'll skip the feature-list.json entry, fix it directly" | Every fix must be traceable in feature-list.json as category=bugfix |
| "Signal file has errors but the intent is clear" | Validator must pass; ask user to fix the file |
| "I'll delete the signal file first, then clean up" | Signal file deletion is the LAST step after everything is verified |
| "The fix is simple, Worker pipeline is overkill" | Worker ensures regression tests, coverage, ST cases, and review — all required |
This skill is invoked by the using-long-task router when bugfix-request.json exists in the project root (highest priority — above increment). After this skill completes:
bugfix-request.json is deletedcategory: "bugfix" feature is in feature-list.json with status: "failing"feature-list.json exists with failing features → long-task-work