202 lines
4.8 KiB
Markdown
202 lines
4.8 KiB
Markdown
# Troubleshooting Guide - Technical Writing Expansion Pack
|
|
|
|
Common issues and solutions for the BMad Technical Writing Expansion Pack.
|
|
|
|
## Installation Issues
|
|
|
|
### Issue: "Expansion pack not found"
|
|
**Symptom**: Cannot activate agents, "bmad-technical-writing not found" error
|
|
|
|
**Cause**: Expansion pack not installed or not in correct location
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Verify installation
|
|
ls ~/.bmad-method/expansion-packs/bmad-technical-writing
|
|
|
|
# If missing, reinstall
|
|
npx bmad-method install
|
|
# Select "Technical Book Writing Studio"
|
|
```
|
|
|
|
### Issue: "Dependencies not resolving"
|
|
**Symptom**: Agent activation fails with missing template/task errors
|
|
|
|
**Cause**: Incomplete installation or corrupted files
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Reinstall expansion pack
|
|
npx bmad-method install --force
|
|
```
|
|
|
|
## Agent Activation Issues
|
|
|
|
### Issue: "Agent not responding"
|
|
**Symptom**: Agent activates but doesn't respond to commands
|
|
|
|
**Cause**: AI context limit reached or agent definition not loaded
|
|
|
|
**Solution**:
|
|
1. Check agent loaded correctly (should show persona description)
|
|
2. Try `*help` command to see available commands
|
|
3. If still unresponsive, re-activate agent
|
|
|
|
### Issue: "Commands not recognized"
|
|
**Symptom**: Agent doesn't recognize `*command-name`
|
|
|
|
**Cause**: Typo in command or command doesn't exist for this agent
|
|
|
|
**Solution**:
|
|
1. Run `*help` to see valid commands for current agent
|
|
2. Check command spelling (commands are case-sensitive)
|
|
3. Verify you're using correct agent for the task
|
|
|
|
### Issue: "Agent dependencies missing"
|
|
**Symptom**: Agent can't find templates, tasks, or checklists
|
|
|
|
**Cause**: Files not in expected location
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Verify file structure
|
|
ls expansion-packs/bmad-technical-writing/templates/
|
|
ls expansion-packs/bmad-technical-writing/tasks/
|
|
ls expansion-packs/bmad-technical-writing/checklists/
|
|
```
|
|
|
|
## Workflow Execution Issues
|
|
|
|
### Issue: "Workflow fails at step X"
|
|
**Symptom**: Workflow stops mid-execution with error
|
|
|
|
**Cause**: Missing prerequisite or validation failure
|
|
|
|
**Solution**:
|
|
1. Check workflow prerequisites (see workflow YAML file)
|
|
2. Verify previous steps completed successfully
|
|
3. Review quality gates - ensure they passed
|
|
|
|
### Issue: "Inputs not accepted"
|
|
**Symptom**: Workflow rejects provided inputs
|
|
|
|
**Cause**: Invalid format or missing required fields
|
|
|
|
**Solution**:
|
|
1. Check template requirements (see template YAML file)
|
|
2. Ensure all required fields provided
|
|
3. Verify format matches expected structure
|
|
|
|
### Issue: "Outputs not produced"
|
|
**Symptom**: Workflow completes but output file not created
|
|
|
|
**Cause**: File path issue or write permissions
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Check directory exists
|
|
mkdir -p docs/planning docs/sections docs/chapters
|
|
|
|
# Check write permissions
|
|
ls -la docs/
|
|
```
|
|
|
|
## Build/Validation Errors
|
|
|
|
### Issue: "npm run validate fails"
|
|
**Symptom**: Validation command reports errors
|
|
|
|
**Cause**: Invalid YAML syntax or missing required fields
|
|
|
|
**Solution**:
|
|
```bash
|
|
# See specific errors
|
|
npm run validate
|
|
|
|
# Common fixes:
|
|
# - Check YAML indentation (use spaces, not tabs)
|
|
# - Verify all required fields present
|
|
# - Check for typos in agent/workflow references
|
|
```
|
|
|
|
### Issue: "YAML syntax error"
|
|
**Symptom**: Parse error when loading configuration
|
|
|
|
**Cause**: Invalid YAML formatting
|
|
|
|
**Solution**:
|
|
1. Check indentation (2 spaces per level)
|
|
2. Verify no tabs used (YAML requires spaces)
|
|
3. Check quotes around special characters
|
|
4. Use YAML validator online
|
|
|
|
## Integration Issues
|
|
|
|
### Issue: "Conflicts with core BMad"
|
|
**Symptom**: Agents or commands conflict
|
|
|
|
**Cause**: Name collision or incompatible versions
|
|
|
|
**Solution**:
|
|
1. Use full agent IDs: `/bmad-tw:agent-name`
|
|
2. Update both core and expansion pack to latest versions
|
|
|
|
### Issue: "Multi-expansion conflicts"
|
|
**Symptom**: Multiple expansion packs interfere with each other
|
|
|
|
**Cause**: Agent name collisions
|
|
|
|
**Solution**:
|
|
1. Use full qualified names: `/bmad-tw:agent` vs `/bmad-cw:agent`
|
|
2. Activate only needed agents
|
|
|
|
## General Troubleshooting Tips
|
|
|
|
### Check Logs
|
|
```bash
|
|
# View debug logs if available
|
|
cat .ai/debug-log.md
|
|
```
|
|
|
|
### Verify Installation
|
|
```bash
|
|
# Check all required files present
|
|
npm run validate
|
|
```
|
|
|
|
### Update to Latest Version
|
|
```bash
|
|
# Pull latest changes
|
|
git pull origin main
|
|
|
|
# Rebuild
|
|
npm run build
|
|
```
|
|
|
|
### Clear Cache
|
|
```bash
|
|
# Remove dist files and rebuild
|
|
rm -rf dist/
|
|
npm run build
|
|
```
|
|
|
|
## Getting Help
|
|
|
|
If your issue isn't listed here:
|
|
|
|
1. **Check Documentation**
|
|
- [User Guide](user-guide.md) - System overview
|
|
- [FAQ](faq.md) - Common questions
|
|
|
|
2. **Community Support**
|
|
- [Discord](https://discord.gg/gk8jAdXWmj) - Real-time help
|
|
- [GitHub Discussions](https://github.com/bmadcode/bmad-method/discussions) - Q&A
|
|
|
|
3. **Report Bugs**
|
|
- [GitHub Issues](https://github.com/bmadcode/bmad-method/issues) - Bug reports
|
|
- Include: Error message, steps to reproduce, environment details
|
|
|
|
---
|
|
|
|
*Troubleshooting Guide - Technical Writing Expansion Pack v1.1.0*
|