|
| 1 | +--- |
| 2 | +name: athas-bug-fix |
| 3 | +description: Standardized workflow for diagnosing and fixing bugs in the Athas codebase. Use when the user mentions "bug", "fix", "issue", or references a GitHub issue number. |
| 4 | +--- |
| 5 | + |
| 6 | +# Athas Bug Fix Workflow |
| 7 | + |
| 8 | +## Context |
| 9 | + |
| 10 | +Athas is a lightweight, cross-platform code editor built with Tauri (Rust backend + React/TypeScript frontend). The codebase has two distinct layers: |
| 11 | + |
| 12 | +- **Frontend** (`src/`): TypeScript/React using Zustand stores, Tauri plugin APIs, xterm.js |
| 13 | +- **Backend** (`src-tauri/`, `crates/`): Rust with Tauri commands, tokio async runtime |
| 14 | + |
| 15 | +## Instructions |
| 16 | + |
| 17 | +### 1. Understand the Bug |
| 18 | + |
| 19 | +- If a GitHub issue number is given, read the issue for reproduction steps and environment details |
| 20 | +- Identify which layer is affected: frontend (TypeScript), backend (Rust), or both |
| 21 | +- Check the issue labels for hints: `Linux`, `macOS`, `Native`, `Git`, `Workspaces`, etc. |
| 22 | + |
| 23 | +### 2. Locate Relevant Code |
| 24 | + |
| 25 | +- **Frontend bugs**: Search in `src/features/<feature>/` — each feature has its own directory with stores, components, and hooks |
| 26 | +- **Backend bugs**: Search in `crates/<crate>/src/` for the relevant Rust crate, or `src-tauri/src/commands/` for Tauri command handlers |
| 27 | +- Use `git log --oneline -- <path>` to see recent changes that may have introduced the bug |
| 28 | +- Check `git log --all --oneline --grep="<keyword>"` for prior fixes in the same area |
| 29 | + |
| 30 | +### 3. Trace the Root Cause |
| 31 | + |
| 32 | +- Follow the data flow from the user action to the bug symptom |
| 33 | +- For frontend bugs: trace from component → hook → store → Tauri invoke |
| 34 | +- For backend bugs: trace from Tauri command → crate function → system call |
| 35 | +- Look for race conditions (especially `void (async () => { ... })()` patterns), stale state, and missing cleanup |
| 36 | +- Check if the bug was introduced by a recent commit (use `git bisect` if needed) |
| 37 | + |
| 38 | +### 4. Implement the Fix |
| 39 | + |
| 40 | +- Match the existing code style: immer middleware for Zustand stores, Tauri command patterns in Rust |
| 41 | +- Preserve existing error handling patterns |
| 42 | +- Add comments explaining non-obvious fixes, referencing the issue number (e.g., `// Fix #581: ...`) |
| 43 | +- Do NOT add logging or debug statements unless the existing code already uses it |
| 44 | + |
| 45 | +### 5. Verify |
| 46 | + |
| 47 | +Run these checks before considering the fix complete: |
| 48 | + |
| 49 | +```bash |
| 50 | +# TypeScript type check (must pass) |
| 51 | +bun run typecheck |
| 52 | + |
| 53 | +# Lint changed files |
| 54 | +npx oxlint <changed-files> |
| 55 | + |
| 56 | +# Rust format check (for Rust changes) |
| 57 | +cargo rustfmt --check <changed-rust-files> |
| 58 | +``` |
| 59 | + |
| 60 | +**Important**: Full `cargo check` requires glib >= 2.70 (Ubuntu 22.04+). If on an older system, verify Rust syntax manually and rely on CI for compilation. |
| 61 | + |
| 62 | +### 6. Cross-Verify |
| 63 | + |
| 64 | +Before finalizing, verify: |
| 65 | +- No removed imports are still used by other code |
| 66 | +- No callers of changed functions are broken |
| 67 | +- The fix doesn't introduce new race conditions |
| 68 | +- Terminal PTY lifecycle is respected (cleanup happens via React useEffect, not synchronously) |
| 69 | + |
| 70 | +## Key Codebase Conventions |
| 71 | + |
| 72 | +- State management: Zustand with immer middleware (`createWithEqualityFn`, `createSelectors`) |
| 73 | +- Async patterns: Background init uses `void (async () => { ... })()` — be careful of race conditions |
| 74 | +- Session persistence: `useSessionStore` with zustand/persist, terminal sessions in localStorage |
| 75 | +- GitHub CLI: Uses `gh` binary via `resolve_gh_binary()` with user shell PATH resolution |
| 76 | +- Performance: Avoid per-entry I/O in loops (stat syscalls, Tauri IPC); prefer lazy resolution |
0 commit comments