# Claude Instructions for Freenet Debugging Wiki

## Purpose
This wiki tracks debugging efforts across the Freenet project ecosystem (freenet-core, river, testing tools, etc.). The goal is to maintain a clear record of what was tested, what happened, and what we think it means.

## Core Principle: Facts vs Theories
**CRITICAL:** Always distinguish between observable facts and interpretations/theories.
- **Facts:** What actually happened, error messages, test results
- **Theories:** What we think caused it, hypotheses, interpretations

## Structure

### 1. Main Debugging Log (`Debugging-Log.md`)
Contains:
- **Active Hypotheses** - All current theories under investigation
- **Current Week's Entries** - Recent debugging activities (last 7 days)
- Links to archived weeks

Each entry should contain:
- Date/time and unique ID (format: `YYYY-MM-DD-NNN`)
- What was tested (exact commands/configuration)
- What happened (results, errors, success/failure)
- NO interpretations or theories in the log entries

### 2. Weekly Archives (`Debugging-Log-YYYY-WNN.md`)
- Entries older than 7 days are moved to weekly archive pages
- Named by ISO week number (e.g., `Debugging-Log-2025-W34.md`)
- Linked from the Archive index page

### 3. Active Hypotheses Section
Located at the top of main `Debugging-Log.md`. Each hypothesis:
- Has a clear theory about what's causing an issue
- Links to relevant log entries as evidence
- Distinguishes "Evidence For" from "Evidence Against"
- Proposes a specific test to confirm/deny

### 4. Archive Index (`Debugging-Archive.md`)
- Index of all weekly archive pages
- Organized by year and month
- Quick navigation to historical entries

### 5. Entry Template (`Debugging-Entry-Template.md`)
Use this template when adding new entries to ensure consistency.

## When Adding New Debugging Information

### Step 1: Document What Happened
Add a new entry to the log with ONLY facts:
```markdown
### 2025-08-28-001
**Time:** 14:30 CDT
**Activity:** Testing River with modified timeout
**Test Configuration:**
```bash
RUST_LOG=debug python gateway_test_framework.py --local --timeout 60
```
**Facts:**
- Test ran for 47 seconds before failing
- Error: "subscription timeout after 30s"
- Gateway showed active connection throughout
**Results:**
- Test failed at subscription step
- No messages exchanged
```

### Step 2: Update or Create Hypotheses (if applicable)
If this test relates to a theory about causation:
- Update existing hypothesis with new evidence
- OR create new hypothesis if discovering new pattern
- Link to the log entry you just created

## Important Guidelines

1. **Never state theories as facts**
   - ❌ "The network layer is causing timeouts"
   - ✅ "Timeout occurred after 30s during subscription"

2. **Be specific about configurations**
   - Include exact commands
   - Note environment variables
   - Specify machine/network setup

3. **Preserve chronological order**
   - Add new entries at the top of the current week section
   - Use sequential numbering for same-day entries
   - Move entries to weekly archives after 7 days

4. **Cross-reference related work**
   - Link between hypotheses and log entries
   - Reference relevant GitHub issues/PRs
   - Note which repositories are involved

## Status Indicators
- 🟡 Under Investigation - actively being tested
- ✅ Confirmed - hypothesis proven correct
- ❌ Disproven - hypothesis proven wrong
- 🔴 Blocked - cannot proceed without external change
- 🟢 Workaround Available - problem identified, temporary solution in place

## Example Workflow

1. Run a test that fails
2. Add log entry with exact details of what happened
3. Review active hypotheses - does this relate to any?
4. If yes: update hypothesis with new evidence
5. If no: consider if this reveals a new pattern worth tracking
6. Plan next test based on hypotheses

## Repository Context
This wiki serves debugging across multiple repositories:
- `freenet-core` - Core peer and network functionality
- `river` - Decentralized chat application
- `freenet-testing-tools` - Test frameworks and utilities
- Others as needed

## Remember
The goal is to systematically eliminate variables and identify root causes. Maintaining clear separation between observations and interpretations helps prevent circular debugging and false conclusions.