Debug

Global Rules: Adheres to rules/archflow-rules.md. Code Mapping # Rule: Always use max(existing #) + 1 for new rows. NEVER reuse deleted numbers.

Model: Try Sonnet first. For complex bugs (multi-file, flow analysis), use Opus.

Debug Workflow

Systematically fix bugs by combining direct code execution with documentation analysis.

Scope

Debug is for E2E issues, not unit test failures.

• Unit test failures -> use /test
• E2E issues (unit tests pass but functionality fails) -> use /debug

Common E2E issues: BE-FE mismatch, API contract violations, integration timing, environment-specific bugs.

Tool Fallback

Tool	Alternative
Read/Grep	Request file path from user -> ask for copy-paste
AskQuestion	"Please select: 1) OptionA 2) OptionB 3) OptionC" format
Shell	Ask user to run commands and paste output

Document Structure

docs/{serviceName}/
  ├── spec.md      # Input (expected behavior)
  ├── arch-be.md   # Input (flow, Code Mapping)
  ├── arch-fe.md   # Input (flow, Code Mapping)
  └── trace.md     # Output (this skill produces)

Execution Path Resolution

Read from arch documents (Tech Stack section):

Field	Source	Example
BE Path	arch-be.md -> Tech Stack -> BE Path	apps/auth-api
FE Path	arch-fe.md -> Tech Stack -> FE Path	apps/auth-web
Run Command (BE)	arch-be.md -> Tech Stack -> Run Command	uv run uvicorn main:app
Run Command (FE)	arch-fe.md -> Tech Stack -> Run Command	npm run dev

---

Phase 0: Skill Entry

0-0. Model and Environment Guidance

Required Documents (docs/{serviceName}/):

• spec.md (required), arch.md (required), trace.md (optional - created if absent)

0-1. Collect Document Input

{"title":"Start Bug Fix","questions":[{"id":"has_requirements","prompt":"Do you have a requirements document? (docs/{serviceName}/spec.md)","options":[{"id":"yes","label":"Yes - I will provide via @filepath"},{"id":"no","label":"No - I don't have it"}]},{"id":"has_design","prompt":"Do you have a design document? (docs/{serviceName}/arch.md)","options":[{"id":"yes","label":"Yes - I will provide via @filepath"},{"id":"no","label":"No - I don't have it"}]},{"id":"has_changelog","prompt":"Do you have a changelog? (docs/{serviceName}/trace.md)","options":[{"id":"yes","label":"Yes - I will provide via @filepath"},{"id":"no","label":"No - Will be created upon completion"}]}]}

Processing:

• Requirements or design no -> General Debug (below)
• Changelog no -> Will create in Phase 3
• All yes -> Request file paths -> Phase 1

General Debug (When documents unavailable)

WARNING: Proceeding without documentation. Bug fixing uses only error log and code analysis. Cannot verify expected behavior or trace design flow.

General Debug Flow:

1. Analyze error message/stack trace
2. Grep + Read related code
3. Estimate cause -> Confirm with user
4. Implement fix
5. Specify separate location for changelog

0-2. Infer serviceName

From file path: docs/alert/spec.md -> serviceName = "alert" -> Output: docs/alert/trace.md

0-3. Verify Error Information

Collect: error message, stack trace, variable state (if available).

"Please describe the error situation. If you have an error message or stack trace, please share it."

---

Phase 1: Document Analysis

1-1. Load Documents

Document	Extract
spec.md	Expected behavior, normal scenario
arch.md	Flow (call order), Code Mapping
trace.md	Recent changes (possible cause)

1-2. Cross-reference Error Location with Design Flow

Error Location (stack trace)
  -> Check Code Mapping (which method)
  -> Check requirements (expected behavior)
  -> Identify mismatch

1-3. Report Analysis Results

## Analysis Results

**Error Location**: {file}:{line} - {error message}
**Design Behavior**: {flow from design document}
**Expected Behavior**: {feature description from requirements}
**Recent Changes**: {possibly related recent changes}
**Estimated Cause**: {cause hypothesis}
**Items Requiring Verification**: {additional checks needed}

Confirm with user: "Is this analysis correct? If yes, I will proceed with the fix."

---

Phase 2: Bug Fix

2-1. Confirm Cause

Read code at error location, verify exact problem point, decide fix direction.

2-2. Implement Fix

Fix matching: requirements, design flow, existing code style.

2-3. E2E Verification (Direct Execution)

Step 1: Read execution config from arch documents (BE/FE Path, Run Commands).

Step 2: Start E2E environment (Shell):

cd {BE Path} && {BE Run Command} &
# Wait for server ready (health check)
cd {FE Path} && {FE Run Command}  # or: npm run test:e2e

Step 3: Verify fix:

Result	Action
Success (no errors)	Proceed to Phase 3
Same error	Re-analyze -> Return to 2-1
New error	Analyze new error -> Return to 2-1

Tight feedback loop: See error -> Fix -> Re-run -> Confirm fix immediately.

---

Phase 3: Call trace Skill (Required)

WARNING: Must call trace skill after analysis/fix completion.

3-1. Call trace Skill

After fix: "Calling trace skill to record this session's results." Or guide: "Analysis complete. Would you like to record this in the changelog?"

3-1.5. Prepare Code Mapping Changes for trace

1. Read arch.md Code Mapping table (get current # numbers)
2. Identify changes: modified rows (MODIFY), new rows (ADD, # = last+1), deleted rows (DELETE)
3. Pass to trace in structured format:

### Code Mapping Changes
| # | Feature | File | Class | Method | Action | Change | Synced |
|---|---------|------|-------|--------|--------|--------|--------|
| 3 | Auth | auth/svc.py | AuthSvc | validate() | Add null check | MODIFY | [ ] |
| 6 | Auth | auth/svc.py | AuthSvc | refresh() | Token refresh | ADD | [ ] |

This structured format enables sync skill to directly apply changes to arch.md

3-2. Recording by Result Type

Result Type	Content to Record
Code fix completed	Symptom, cause, fix content, design impact
External cause identified	Symptom, external cause, recommended action
Investigation ongoing/failed	Symptom, investigation content, next steps

3-3. If Not Called

User can manually call: "trace" or "write changelog". Same session context will be used.

---

Phase 4: Completion Report

## Bug Fix Complete

### Analysis/Fix Summary
| Item | Content |
|------|---------|
| Symptom | {original bug symptom} |
| Cause | {identified cause} |
| Result Type | Code fix / External cause / Under investigation |
| Modified Files | {file list or "none"} |

### Test Method (if fixed)
1. {Verify with reproduction scenario}
2. {How to verify normal behavior}

### Recurrence Prevention (Required Checklist)
- [ ] Add tests (if applicable)
- [ ] Add guard/validation logic (if applicable)
- [ ] Add logging/monitoring (if applicable)

**Recurrence Probability**: High / Medium / Low

WARNING: Have you recorded this in the changelog? Call "trace" or "write changelog". External causes and investigation failures are also worth recording.

---

Integration Flow

[spec] -> spec.md -> [arch] -> arch.md -> [build] -> Implementation
  -> (Bug occurs) -> [debug] -> Analysis/fix
    -> [trace] -> trace.md -> (design impact) -> [sync] -> arch.md

Important Notes

1. Runtime Info Helps - Providing error messages and stack traces improves effectiveness
2. Documentation Dependency - Docs must be accurate; if doc-impl mismatch, sync first
3. Changelog Management - All bug fixes should be recorded in trace
4. Complex Bugs - Multi-file bugs -> use Opus; if unresolved, repeat analysis -> confirmation -> re-analysis