| 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
