nk-refresh

Files (1)

• SKILL.md

SKILL.md (first lines)

# REFRESH Command - Systematic Re-Diagnosis

This command performs systematic re-diagnosis when an AI agent gets stuck on a coding task or when a previous attempt has failed to resolve an issue.

## Key Principles

### Do NOT Jump to Solutions

- No fixing until the root cause is CONFIRMED through investigation
- Evidence-based diagnosis only
- Systematic exploration, not trial-and-error

### Broaden Before Narrowing

- Start with a wide view of the system
- Map the architecture
- Then narrow down based on evidence

### Document Everything

- All hypotheses
- All investigation steps
- All evidence found
- All conclusions drawn

### Transparent Communication

- Explain what you're investigating and why
- Share findings as you go
- Be clear about confidence level

## Workflow

Based on the persistent user query about a problem that likely failed to resolve previously, follow these steps:

### Step 1: Load Memory Bank Files

Read:
- `memory-bank/active/projectbrief.md`
- `memory-bank/systemPatterns.md`
- `memory-bank/techContext.md`

### Step 2: Progress Tracking

**CRITICAL**: Plan and track your diagnostics in a unique Task List File, distinct from any parent task's Task List. 

- Locate or create: `memory-bank/active/troubleshooting/troubleshooting-<YYYYMMDD-HHmmss>.md`
- This task list is for THIS diagnostic session only
- Always identify the correct Task List File before making updates

### Step 3: Step Back & Re-Scope

**Forget the specifics of the last failed attempt.** Broaden your focus.

- Identify the *core functionality* or *system component(s)* involved in the reported problem
  - Examples: authentication flow, data processing pipeline, specific UI component interaction, infrastructure resource provisioning
- Do NOT assume you know the cause yet
- Think about the system holistically

### Step 4: Map the Relevant System Structure

Use tools to **map out the high-level structure and key interaction points** of the identified component(s):

- `list_dir`: Understand directory structure
- `glob_file_search`: Find relevant files by pattern
- `codebase_search`: Understand how components interact
- `read_file`: Read configuration files, entry points

**Goal**: Gain a "pyramid view" - see the overall architecture first before diving into details.

**Document findings** in the troubleshooting task list.

### Step 5: Hypothesize Potential Root Causes (Broadly)

Based on the system map and the problem description, generate a *broad* list of potential areas where the root cause might lie:

Examples:
- Configuration error
- Incorrect API call
- Upstream data issue
- Logic flaw in module X
- Dependency conflict
- Infrastructure misconfiguration
- Incorrect permissions
- Path resolution issues
- Environment-specific problems

**Do NOT pick one yet.** List them all.

### Step 6: Systematic Investigation & Evidence Gathering

**Prioritize and investigate** the most likely hypotheses using targeted tool usage:

#### Step 6a: Validate Configurations

- Use `read_file` to check *all* relevant configuration files
- Look for typos, wrong paths, incorrect values
- Verify environment-specific configurations

#### Step 6b: Trace Execution Flow

- Use `grep` or `codebase_search` to trace the execution path related to the failing functionality
- Add temporary, descriptive logging via `search_replace` if necessary and safe
  - Request approval if the change is risky
- Pinpoint where the failure actually occurs

#### Step 6c: Check Dependencies & External Interactions

- Verify versions and statuses of dependencies
- If external systems are involved, use safe commands to assess their state
  - Use `run_terminal_cmd` for diagnostics like status checks
  - Set `require_user_approval=true` if needed

#### Step 6d: Examine Logs

- If logs are accessible and relevant, retrieve them
- Analyze recent entries related to the failure
- Look for error messages, stack traces, warnings

From Texarkanine/nervouscsstem, AGPL-3.0.

More from Texarkanine/nervouscsstem