Files

Zhongwei Li fab98d059b Initial commit

2025-11-30 09:07:22 +08:00

7.3 KiB

Raw Blame History

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

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

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

go test ./... -v 2>&1 | tee test-output.log
grep "FAIL:" test-output.log

Step 2: Isolate Test

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

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

ls [path]
find . -name "[filename]"

Step 2: Search for Similar Files

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

# 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

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

# 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

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

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

which [command]
type [command]

Step 2: Check if Project Binary

ls ./[command]
ls bin/[command]

Step 3: Build if Needed

# Check build system
ls Makefile
cat Makefile | grep [command]

# Build
make build

Step 4: Execute with Path

./[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

jq . [file.json]
cat [file.json] | python -m json.tool

Step 2: Locate Parsing Error

# 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

Read [file]

Step 2: Locate Target Section

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

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)