gcvb

# Diagnostic Reasoning Protocol

When investigating software, infrastructure, UI, database, networking, deployment, or application issues:

## Rule 1: Separate Observations From Explanations

Treat user explanations as hypotheses, not facts.

Example:

User says:
"Changing the profile picture broke the avatar."

Do not conclude:

"Changing the profile picture caused the bug."

Instead conclude:

"The avatar is not rendering. The user's proposed cause is avatar replacement logic. This remains unverified."

---

## Rule 2: Prioritize Observable Evidence

Evidence hierarchy:

1. Source code
2. Database records
3. Server logs
4. Browser console output
5. Network requests
6. Screenshots
7. User workflow description
8. User assumptions

Higher evidence levels override lower evidence levels.

---

## Rule 3: Request Missing Evidence

Before proposing fixes, determine whether enough evidence exists.

If not, request:

* Screenshots
* Screen recordings
* Error messages
* Browser console output
* Network request traces
* Database records
* Relevant source files
* Reproduction steps

Example:

"Please provide:

1. Screenshot of the failure
2. Exact steps performed
3. Browser console errors
4. Current image URL"

---

## Rule 4: Reconstruct The User Flow

Identify:

Initial State
↓
User Action
↓
Expected Result
↓
Observed Result
↓
Failure Point

Do not skip any stage.

---

## Rule 5: Verify Before Patching

Never modify code based solely on assumptions.

Before patching:

* Confirm the symptom
* Confirm the affected component
* Confirm the probable root cause

Only then implement a fix.

---

## Rule 6: Distinguish Confidence Levels

Always state:

Confirmed:

* Directly observed evidence

Likely:

* Supported by evidence but not proven

Possible:

* Plausible but unverified

Unknown:

* Insufficient evidence

---

## Rule 7: Investigate Shared Systems

If the same failure appears in multiple locations:

Example:

* Header avatar broken
* Profile avatar broken
* Chat avatar broken

Prefer investigating:

* Shared database fields
* Shared helper functions
* Shared API endpoints
* Shared rendering utilities

before investigating page-specific code.

---

## Rule 8: Look For Contradictory Evidence

Actively search for information that disproves the current theory.

If evidence contradicts the current explanation:

* Update the model
* Discard invalid assumptions
* Re-evaluate root cause

---

## Rule 9: Use Screenshots As Data Sources

Analyze screenshots for:

* Missing images
* Layout breaks
* Overflow
* Typography changes
* Broken icons
* Incorrect state transitions
* Unexpected text
* Browser-rendered fallback content

Treat screenshots as evidence, not decoration.

---

## Rule 10: Diagnose Before Repair

Preferred sequence:

Observe
↓
Collect Evidence
↓
Reconstruct Workflow
↓
Identify Failure Point
↓
Verify Cause
↓
Design Fix
↓
Implement Fix
↓
Validate Result

Do not skip directly from symptom to patch.

---

Core Principle

"The user reports the experience.
The evidence reveals the system state.
The diagnosis must come from the evidence, not the assumption."