# Diagnostic Workflows

**Version**: 2.0
**Source**: Bootstrap-003 Error Recovery Methodology
**Last Updated**: 2025-10-18
**Coverage**: 78.7% of errors (8 workflows)

Step-by-step diagnostic procedures for common error categories.

---

## Workflow 1: Build/Compilation Errors (15.0%)

**MTTD**: 2-5 minutes

### Symptoms
- `go build` fails
- Error messages: `*.go:[line]:[col]: [error]`

### Diagnostic Steps

**Step 1: Identify Error Location**
```bash
go build 2>&1 | tee build-error.log
grep "\.go:" build-error.log
```

**Step 2: Classify Error Type**
- Syntax error (braces, semicolons)
- Type error (mismatches)
- Import error (unused/missing)
- Definition error (undefined references)

**Step 3: Inspect Context**
```bash
sed -n '[line-5],[line+5]p' [file]
```

### Tools
- `go build`, `grep`, `sed`
- IDE/editor

### Success Criteria
- Root cause identified
- Fix approach clear

### Automation
Medium (linters, IDE integration)

---

## Workflow 2: Test Failures (11.2%)

**MTTD**: 3-10 minutes

### Symptoms
- `go test` fails
- `FAIL` messages in output

### Diagnostic Steps

**Step 1: Identify Failing Test**
```bash
go test ./... -v 2>&1 | tee test-output.log
grep "FAIL:" test-output.log
```

**Step 2: Isolate Test**
```bash
go test ./internal/parser -run TestParseSession
```

**Step 3: Analyze Failure**
- Assertion failure (expected vs actual)
- Panic (runtime error)
- Timeout
- Setup failure

**Step 4: Inspect Code/Data**
```bash
cat [test_file].go | grep -A 20 "func Test[Name]"
cat tests/fixtures/[fixture]
```

### Tools
- `go test`, `grep`
- Test fixtures

### Success Criteria
- Understand why assertion failed
- Know expected vs actual behavior

### Automation
Low (requires understanding intent)

---

## Workflow 3: File Not Found (18.7%)

**MTTD**: 1-3 minutes

### Symptoms
- `File does not exist`
- `No such file or directory`

### Diagnostic Steps

**Step 1: Verify Non-Existence**
```bash
ls [path]
find . -name "[filename]"
```

**Step 2: Search for Similar Files**
```bash
find . -iname "*[partial_name]*"
ls [directory]/
```

**Step 3: Classify Issue**
- Path typo (wrong name/location)
- File not created yet
- Wrong working directory
- Case sensitivity issue

**Step 4: Fuzzy Match**
```bash
# Use automation tool
./scripts/validate-path.sh [attempted_path]
```

### Tools
- `ls`, `find`
- `validate-path.sh` (automation)

### Success Criteria
- Know exact cause (typo vs missing)
- Found correct path or know file needs creation

### Automation
**High** (path validation, fuzzy matching)

---

## Workflow 4: File Size Exceeded (6.3%)

**MTTD**: 1-2 minutes

### Symptoms
- `File content exceeds maximum allowed tokens`
- Read operation fails with size error

### Diagnostic Steps

**Step 1: Check File Size**
```bash
wc -l [file]
du -h [file]
```

**Step 2: Determine Strategy**
- Use offset/limit parameters
- Use grep/head/tail
- Process in chunks

**Step 3: Execute Alternative**
```bash
# Option A: Pagination
Read [file] offset=0 limit=1000

# Option B: Selective reading
grep "pattern" [file]
head -n 1000 [file]
```

### Tools
- `wc`, `du`
- Read tool with pagination
- `grep`, `head`, `tail`
- `check-file-size.sh` (automation)

### Success Criteria
- Got needed information without full read

### Automation
**Full** (size check, auto-pagination)

---

## Workflow 5: Write Before Read (5.2%)

**MTTD**: 1-2 minutes

### Symptoms
- `File has not been read yet`
- Write/Edit tool error

### Diagnostic Steps

**Step 1: Verify File Exists**
```bash
ls [file]
```

**Step 2: Determine Operation Type**
- Modification → Use Edit tool
- Complete rewrite → Read then Write
- New file → Write directly (no Read needed)

**Step 3: Add Read Step**
```bash
Read [file]
Edit [file] old_string="..." new_string="..."
```

### Tools
- Read, Edit, Write tools
- `check-read-before-write.sh` (automation)

### Success Criteria
- File read before modification
- Correct tool chosen (Edit vs Write)

### Automation
**Full** (auto-insert Read step)

---

## Workflow 6: Command Not Found (3.7%)

**MTTD**: 2-5 minutes

### Symptoms
- `command not found`
- Bash execution fails

### Diagnostic Steps

**Step 1: Identify Command Type**
```bash
which [command]
type [command]
```

**Step 2: Check if Project Binary**
```bash
ls ./[command]
ls bin/[command]
```

**Step 3: Build if Needed**
```bash
# Check build system
ls Makefile
cat Makefile | grep [command]

# Build
make build
```

**Step 4: Execute with Path**
```bash
./[command] [args]
# OR
PATH=$PATH:./bin [command] [args]
```

### Tools
- `which`, `type`
- `make`
- Project build system

### Success Criteria
- Command found or built
- Can execute successfully

### Automation
Medium (can detect and suggest build)

---

## Workflow 7: JSON Parsing Errors (6.0%)

**MTTD**: 3-8 minutes

### Diagnostic Steps

**Step 1: Validate JSON Syntax**
```bash
jq . [file.json]
cat [file.json] | python -m json.tool
```

**Step 2: Locate Parsing Error**
```bash
# Error message shows line/field
# View context around error
sed -n '[line-5],[line+5]p' [file.json]
```

**Step 3: Classify Issue**
- Syntax error (commas, braces)
- Type mismatch (string vs int)
- Missing field
- Schema change

**Step 4: Fix or Update**
- Fix JSON structure
- Update Go struct definition
- Update test fixtures

### Tools
- `jq`, `python -m json.tool`
- Go compiler (for schema errors)

### Success Criteria
- JSON is valid
- Schema matches code expectations

### Automation
Medium (syntax validation yes, schema fix no)

---

## Workflow 8: String Not Found (Edit) (3.2%)

**MTTD**: 1-3 minutes

### Symptoms
- `String to replace not found in file`
- Edit operation fails

### Diagnostic Steps

**Step 1: Re-Read File**
```bash
Read [file]
```

**Step 2: Locate Target Section**
```bash
grep -n "target_pattern" [file]
```

**Step 3: Copy Exact String**
- View file content
- Copy exact string (including whitespace)
- Don't retype (preserves formatting)

**Step 4: Retry Edit**
```bash
Edit [file] old_string="[exact_copied_string]" new_string="[new]"
```

### Tools
- Read tool
- `grep -n`

### Success Criteria
- Found exact current string
- Edit succeeds

### Automation
High (auto-refresh before edit)

---

## Diagnostic Workflow Selection

### Decision Tree

```
Error occurs
├─ Build fails? → Workflow 1
├─ Test fails? → Workflow 2
├─ File not found? → Workflow 3 ⚠️ AUTOMATE
├─ File too large? → Workflow 4 ⚠️ AUTOMATE
├─ Write before read? → Workflow 5 ⚠️ AUTOMATE
├─ Command not found? → Workflow 6
├─ JSON parsing? → Workflow 7
├─ Edit string not found? → Workflow 8
└─ Other? → See taxonomy.md
```

---

## Best Practices

### General Diagnostic Approach

1. **Reproduce**: Ensure error is reproducible
2. **Classify**: Match to error category
3. **Follow workflow**: Use appropriate diagnostic workflow
4. **Document**: Note findings for future reference
5. **Verify**: Confirm diagnosis before fix

### Time Management

- Set time limit per diagnostic step (5-10 min)
- If stuck, escalate or try different approach
- Use automation tools when available

### Common Mistakes

❌ Skip verification steps
❌ Assume root cause without evidence
❌ Try fixes without diagnosis
✅ Follow workflow systematically
✅ Use tools/automation
✅ Document findings

---

**Source**: Bootstrap-003 Error Recovery Methodology
**Framework**: BAIME (Bootstrapped AI Methodology Engineering)
**Status**: Production-ready, validated with 1336 errors