CLAUDE

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:

### 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.