remy-debug

Files (5)

• README.md
• README_zh.md
• SKILL.md
• diagnosis_template.md
• output_schema.json

SKILL.md (first lines)

# Remy Debug Protocol

Diagnosis-only debugging skill. Produces a structured diagnosis report and an evidence packet compatible with `/remy-patch`. Does NOT modify source code.

## 0. Configuration

| Environment Variable | Default | Description |
| :--- | :--- | :--- |
| `DEBUG_MAX_HYPOTHESES` | `3` | Maximum hypothesis iterations before circuit breaker triggers. |

### Argument Parsing

```
/remy-debug [symptom] [--since <git-ref>]
```

1. If no argument provided: enter **Guided Mode** (Phase 0.1).
2. If argument contains a test file path pattern (e.g., `test_*.py`, `*.test.ts`, `*_test.go`): treat as **test command**.
3. If argument matches `<file>:<line>` pattern: treat as **location reference**.
4. Otherwise: treat as **error description**.
5. `--since <ref>`: optional git revision to scope regression analysis.

---

## Phase 0: Symptom Capture

**Goal**: Obtain a concrete, actionable symptom description.

### 0.1 Guided Mode (no arguments)

Use `AskUserQuestion` to collect:
- What is the observed behavior?
- What is the expected behavior?
- When did it start (if known)?

### 0.2 Test Command Mode

1. Check the current mode and authorization before running the existing test command via `Bash` (or `PowerShell` on Windows). If execution is not permitted, use available error output or report the missing observation; do not run a probe in native Plan mode.
2. Capture exit code, stdout, stderr.
3. If exit code = 0: report "Test passes. No failure to diagnose." → HALT.
4. Record full error output as the **Symptom Record**.

### 0.3 Error Description Mode

Record the user-provided text as the **Symptom Record**.

### 0.4 Location Reference Mode

1. `Read` the specified file at the given line (±20 lines context).
2. Record the code region as the **Symptom Record**.

**Phase 0 Exit**: A Symptom Record exists. Proceed to Phase 1.

---

## Phase 1: Localization

**Goal**: Identify suspect files and narrow the search space.

### 1.1 Stack Trace Parsing

If the Symptom Record contains a stack trace or error with file paths:
1. Extract all file paths and line numbers mentioned.
2. These become the **Suspect Set**.

If no parseable paths exist:
1. `Grep` for keywords from the error message (function names, error codes, unique strings).
2. Results become the **Suspect Set**.

### 1.2 Impact Analysis (Conditional)

1. Check: `Bash("test -f .claude/logic_index.db && echo EXISTS || echo MISSING")`.
2. **EXISTS**: Run `Bash("python \"~/.claude/skills/remy-index/impact.py\" <suspect_file_1> <suspect_file_2> ...")`.
    *   **MCP alternative**: If `remy-index` MCP server is active, `query_impact` / `query_callers` tools provide equivalent data without subprocess overhead.
   - If exit code = 0: record output as **Dependency Map**.
   - If exit code = 2: skip (no call graph data).
3. **MISSING**: Skip impact analysis.

### 1.3 Git History Analysis

1. For each file in the Suspect Set:
   ```
   git log -5 --oneline -- <file>
   ```
2. If `--since <ref>` was provided:
   ```
   git diff <ref>..HEAD -- <suspect_files>
   ```
3. Record recent changes as **Change History**.

### 1.4 Context Read

For each file in the Suspect Set:
- If Dependency Map provides line ranges and file exceeds 500 lines: precision-read relevant ranges.
- Otherwise: read the full file.

**Phase 1 Exit**: Suspect Set, Dependency Map (if available), Change History, and suspect code are in context.

---

## Phase 2: Hypothesis Loop

**Goal**: Iteratively form and test hypotheses until supported failure mechanism is identified or circuit breaker triggers.

Initialize: `_hypothesis_count = 0`

### 2.1 Form Hypothesis

Based on available evidence (Symptom Record, suspect code, Change History, Dependency Map), state:
- **Hypothesis**: One sentence describing a possible failure mechanism and the observation it explains.
- **Evidence state**: Use `style.md`'s shared `[✓]`, `[~]`, `[?]`, or `[×]` for the specific claim. A proposed explanation usually remains `[~]` with supporting evidence or `[?]` when evidence is insufficient. Add an acquired-basis attribute only when useful, such as `[~｜源码+实测]`; state citations, scope, and unresolved premises separately.
- **Probe Design**: Identify the next permitted observation that could distinguish the hypothesis from alternatives. Question types and optional investigation methods follow `rules/reasoning-and-decisions.md`; a method label does not authorize a test or script.

### 2.2 Execute Probe

Probes follow the Observation Task Protocol (`output-styles/system-architect.md` §4.1). Debug-specific extension: re-running existing tests is allowed only within applicable authorization and an execution-permitting mode (the test runner may touch its own cache directories). Native Plan mode does not execute probes. Creating a temporary script is not permitted by this extension.

Allowed probe types within those boundaries (read-only + existing test execution):
- `Read` a specific code region

From MyPeacefulValentine/Remy-CC, MIT.

More from MyPeacefulValentine/Remy-CC