📘 Khy-OS 文档站 🧭 新手先读：核心概念

# Debug — Systematic Debugging

# Debug — Systematic Debugging#

## Purpose#

Debug issues by following a systematic workflow: reproduce, isolate, identify root cause, and propose a fix.

## Workflow#

1. Understand the Problem: Gather information from the user:
   - What is the expected behavior?
   - What is the actual behavior?
   - When did it start happening?
   - Any recent changes that might be related?

1. Reproduce: Attempt to reproduce the issue:
   - Run the failing command or test.
   - Check logs for error messages and stack traces.
   - Note the exact error output.

1. Isolate: Narrow down the root cause:
   - Trace the code path from the error back to its origin.
   - Check recent git changes to the affected files (`git log -p <file>`).
   - Look for common issues: null references, type mismatches, missing imports, race conditions.
   - Search for related issues in the codebase using Grep.

1. Identify Root Cause: Determine the exact cause:
   - Pinpoint the file, function, and line where the bug originates.
   - Explain why the current code fails.
   - Check if the bug exists in other similar code paths.

1. Propose Fix: Suggest a concrete fix:
   - Show the minimal code change needed.
   - Explain why the fix works.
   - Note any edge cases the fix should handle.
   - Suggest a test to prevent regression.

## Guidelines#

- Start with the most likely cause and work outward.
- Read error messages carefully — they often point directly to the problem.
- Check for environment-specific issues (Node version, OS, missing env vars).
- Do not apply fixes automatically — present them for user approval first.