How to Report a Bug in DeepSeek-Reasonix: The Complete 2024 Guide

Report bugs in DeepSeek-Reasonix by opening a GitHub issue with a clear title, reproducibility steps, expected vs. actual behavior, environment details, and the correct v1 or v2 label.

DeepSeek-Reasonix is an open-source AI coding assistant with a multi-subsystem Go architecture. When you encounter a defect, following the project's established bug reporting protocol—defined in CONTRIBUTING.md and MIGRATING.md—ensures maintainers can reproduce and fix issues efficiently.

Where to Submit Bug Reports

All bug reports for DeepSeek-Reasonix flow through GitHub Issues. The repository uses a structured template system to standardize incoming reports.

According to the source code in CONTRIBUTING.md, you must:

1. Navigate to the project's GitHub Issues page
2. Click "New issue"
3. Select the bug report template

The template enforces specific sections that maintainers rely on for triage.

Required Information for Every Bug Report

A complete DeepSeek-Reasonix bug report contains six essential components. Missing any of these typically results in a request for more information, delaying resolution.

Steps to Reproduce

Provide a numbered list that any maintainer can execute. Include exact commands, configuration files, and input prompts.

# Example: CLI reproduction script for a file-encoding bug

cat > bug-repro.sh <<'EOF'
#!/usr/bin/env sh
reasonix run "write a file that contains a non-UTF-8 character"
EOF
chmod +x bug-repro.sh

Attach this script directly to your GitHub issue.

Expected vs. Actual Behavior

State clearly what should happen versus what actually occurs. For crashes, include the full stack trace.

Environment Details

Include:

• Go version (go version)
• Operating system and architecture
• Reasonix version (reasonix version)
• Relevant configuration from reasonix.toml

# Example: Minimal config that triggers a provider bug

[providers.myprovider]
kind = "openai"
model = "deepseek-chat"
api_key = "REDACTED"

Relevant Logs

Capture output from:

• CLI/TUI sessions
• Desktop application logs
• Provider API responses (with sensitive data redacted)

Critical: Label Your Issue Correctly (v1 vs v2)

DeepSeek-Reasonix maintains two distinct code lines. Accurate labeling determines which codebase receives the fix.

Label	Codebase	Status	Use When
v2	Go implementation	Active development	Reporting bugs in current CLI, desktop app, or providers
v1	Legacy TypeScript	Maintenance mode only	Bugs in deprecated code, per docs/MIGRATING.md

As documented in MIGRATING.md, the v2 label applies to nearly all contemporary bug reports. Use v1 only when specifically working with legacy TypeScript components.

Subsystem-Specific Bug Reporting Tips

Understanding where bugs originate helps you provide targeted reproduction steps. The repository structure in main-v2 organizes functionality into distinct packages:

CLI Bugs (internal/cli/)

Most user-facing issues surface in the command-line interface. The entry point at cmd/reasonix handles argument parsing, configuration loading, and session initialization.

When reporting CLI bugs:

• Include the exact command with all flags
• Specify whether running in TUI mode (-tui) or headless
• Attach ~/.config/reasonix/history.json if relevant

Desktop Application Bugs (desktop/)

The Wails-based desktop application uses WebView2 on Windows and native web runtimes elsewhere. Report rendering issues, window management problems, or IPC failures here.

Include:

• WebView2 runtime version (Windows)
• Screenshots or screen recordings for UI glitches
• Browser console logs from the DevTools

Provider Bugs (internal/provider/)

API-level issues with OpenAI-compatible or DeepSeek-specific backends belong here. Issues include authentication failures, rate limiting, malformed responses, or streaming interruptions.

Provide:

• Provider configuration (with api_key redacted)
• HTTP response traces (with REASONIX_DEBUG=1 if available)
• Timestamp of failed request for server-side correlation

Built-in Tool Bugs (internal/tool/builtin/)

File operations, process spawning, and sandboxing issues trace to this package. Common problems include:

• Permission errors in write_file or read_file
• Encoding mishandling in str_replace
• Sandbox escape attempts

Optional: Attach a Minimal Reproducible Example

While not strictly required, a minimal reproducible example accelerates triage significantly. The best examples:

• Contain fewer than 20 lines of code or configuration
• Fail deterministically across clean environments
• Isolate the bug from project-specific context

What Happens After You Submit

Maintainers follow a structured response workflow:

1. Triage (24-48 hours): Issue labeled and routed to appropriate subsystem maintainer
2. Reproduction: Maintainer attempts to reproduce using your steps
3. Investigation: Root cause analysis with potential workaround provided
4. Fix PR: Change proposed, linked to your issue
5. Regression test: CI pipeline adds automated test targeting the failure
6. Closure: Issue closed when fix merges to main-v2

Continue responding to clarification requests promptly. The internal/cli/ test suite and subsystem-specific CI gates rely on accurate reproduction steps to generate regression tests.

Summary

• Submit all DeepSeek-Reasonix bugs through GitHub Issues using the provided template
• Include steps to reproduce, expected/actual behavior, environment details, and logs
• Label correctly: v2 for current Go code, v1 only for legacy TypeScript
• Reference the appropriate subsystem: internal/cli/, desktop/, internal/provider/, or internal/tool/builtin/
• Attach minimal reproduction scripts when possible to speed up CI integration

Frequently Asked Questions

Do I need to know Go to report a bug in DeepSeek-Reasonix?

No. While understanding the repository structure helps position your report, you only need to describe the problem clearly and provide reproduction steps. Maintainers handle the implementation details in internal/ packages. Focus on what you observed and how to trigger it.

What if I'm not sure whether a bug is in v1 or v2?

Default to v2. As documented in MIGRATING.md, the v2 codebase (current Go implementation) is the active development line. Only apply v1 if you are explicitly running legacy TypeScript code from the pre-Go era. When in doubt, mention your installation method and version output from reasonix version.

How quickly do maintainers respond to bug reports?

Typical initial triage occurs within 24-48 hours for well-structured reports. Issues missing environment details or reproduction steps may sit longer pending clarification. Critical security bugs or data-loss scenarios receive priority handling regardless of report completeness.

Can I suggest a fix alongside my bug report?

Yes. The project welcomes pull requests that include both bug description and fix. Follow the format in CONTRIBUTING.md, reference the issue number, and ensure your change includes a regression test in the relevant subsystem's test package (e.g., internal/provider/provider_test.go).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}