troubleshooting-guardrails

name	troubleshooting-guardrails
description	Guardrails for debugging and troubleshooting. Auto-loaded when Droid encounters errors, test failures, or build issues. Prevents context drift and tech stack swaps during error recovery.
user-invocable	false

Troubleshooting Guardrails

When you encounter an error, build failure, or test failure, follow this protocol BEFORE proposing any fix:

Step 1: Re-read Context

• Re-read AGENTS.md for technology constraints
• If a spec exists in .factory/docs/, re-read it
• Identify which requirement or task the current work relates to

Step 2: Diagnose Within Bounds

• Read the actual error message and stack trace carefully
• Identify the root cause, not just the symptom
• Check if the error is in OUR code or a dependency

Step 3: Propose Minimal Fix

The fix MUST:

• Stay within the approved tech stack (see AGENTS.md and tech-stack-steering skill)
• Be the smallest change that resolves the issue
• Not introduce new dependencies without explicit approval
• Not delete or weaken existing tests
• Not remove error handling or logging

Step 4: Forbidden Troubleshooting Actions

NEVER do any of these to fix a bug:

• Switch from one framework/library to another
• Downgrade TypeScript strictness or add @ts-ignore
• Disable linting rules
• Remove type safety (casting to any)
• Delete tests that are now failing
• Comment out code "temporarily"
• Add try/catch that swallows errors silently

Step 5: Escalation

If you cannot fix the issue within these bounds after 2 attempts:

• Summarize what you tried and why it failed
• Explain what constraint is blocking the fix
• Ask the user for guidance rather than breaking boundaries