Codex Debug-With-File Prompt

Overview

Enhanced evidence-based debugging with

documented exploration process

. Records understanding evolution, consolidates insights, and uses analysis to correct misunderstandings.

Core workflow

Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify

Key enhancements over /prompts:debug

:

understanding.md

Timeline of exploration and learning

Analysis-assisted correction

Validates and corrects hypotheses

Consolidation

Simplifies proven-wrong understanding to avoid clutter
Learning retention: Preserves what was learned, even from failed attempts Target Bug $BUG Execution Process Session Detection: ├─ Check if debug session exists for this bug ├─ EXISTS + understanding.md exists → Continue mode └─ NOT_FOUND → Explore mode Explore Mode: ├─ Locate error source in codebase ├─ Document initial understanding in understanding.md ├─ Generate testable hypotheses with analysis validation ├─ Add NDJSON logging instrumentation └─ Output: Hypothesis list + await user reproduction Analyze Mode: ├─ Parse debug.log, validate each hypothesis ├─ Use analysis to evaluate hypotheses and correct understanding ├─ Update understanding.md with: │ ├─ New evidence │ ├─ Corrected misunderstandings (strikethrough + correction) │ └─ Consolidated current understanding └─ Decision: ├─ Confirmed → Fix root cause ├─ Inconclusive → Add more logging, iterate └─ All rejected → Assisted new hypotheses Fix & Cleanup: ├─ Apply fix based on confirmed hypothesis ├─ User verifies ├─ Document final understanding + lessons learned ├─ Remove debug instrumentation └─ If not fixed → Return to Analyze mode Implementation Details Session Setup & Mode Detection Step 0: Determine Project Root 检测项目根目录，确保 .workflow/ 产物位置正确： PROJECT_ROOT = $( git rev-parse --show-toplevel 2

/dev/null || pwd ) 优先通过 git 获取仓库根目录；非 git 项目回退到 pwd 取当前绝对路径。存储为 {projectRoot} ，后续所有 .workflow/ 路径必须以此为前缀。 const getUtc8ISOString = ( ) => new Date ( Date . now ( ) + 8 * 60 * 60 * 1000 ) . toISOString ( ) const projectRoot = bash ( 'git rev-parse --show-toplevel 2>/dev/null || pwd' ) . trim ( ) const bugSlug = "$BUG" . toLowerCase ( ) . replace ( / [ ^ a - z 0 - 9 ] + / g , '-' ) . substring ( 0 , 30 ) const dateStr = getUtc8ISOString ( ) . substring ( 0 , 10 ) const sessionId = DBG- ${ bugSlug } - ${ dateStr } const sessionFolder = ${ projectRoot } /.workflow/.debug/ ${ sessionId } const debugLogPath = ${ sessionFolder } /debug.log const understandingPath = ${ sessionFolder } /understanding.md const hypothesesPath = ${ sessionFolder } /hypotheses.json // Auto-detect mode const sessionExists = fs . existsSync ( sessionFolder ) const hasUnderstanding = sessionExists && fs . existsSync ( understandingPath ) const logHasContent = sessionExists && fs . existsSync ( debugLogPath ) && fs . statSync ( debugLogPath ) . size

0 const mode = logHasContent ? 'analyze' : ( hasUnderstanding ? 'continue' : 'explore' ) if ( ! sessionExists ) { bash ( mkdir -p ${ sessionFolder } ) } Explore Mode Step 1.1: Locate Error Source // Extract keywords from bug description const keywords = extractErrorKeywords ( "$BUG" ) // Search codebase for error locations const searchResults = [ ] for ( const keyword of keywords ) { const results = Grep ( { pattern : keyword , path : "." , output_mode : "content" , "-C" : 3 } ) searchResults . push ( { keyword , results } ) } // Identify affected files and functions const affectedLocations = analyzeSearchResults ( searchResults ) Step 1.2: Document Initial Understanding Create understanding.md :

Understanding Document

Session ID

${sessionId}

Bug Description

$BUG
**
Started
**: ${getUtc8ISOString()}

Exploration Timeline

Iteration 1 - Initial Exploration (${timestamp})

Current Understanding Based on bug description and initial code search: - Error pattern: ${errorPattern} - Affected areas: ${affectedLocations.map(l => l.file).join(', ')} - Initial hypothesis: ${initialThoughts}

Evidence from Code Search ${searchResults.map(r => ** Keyword: "${r.keyword}" ** - Found in: ${r.results.files.join(', ')} - Key findings: ${r.insights}).join('\n')}

Next Steps

Generate testable hypotheses

Add instrumentation

Await reproduction

Current Consolidated Understanding ${initialConsolidatedUnderstanding} Step 1.3: Generate Hypotheses Analyze the bug and generate 3-5 testable hypotheses: // Hypothesis generation based on error pattern const HYPOTHESIS_PATTERNS = { "not found|missing|undefined|未找到" : "data_mismatch" , "0|empty|zero|registered" : "logic_error" , "timeout|connection|sync" : "integration_issue" , "type|format|parse" : "type_mismatch" } function generateHypotheses ( bugDescription , affectedLocations ) { // Generate targeted hypotheses based on error analysis // Each hypothesis includes: // - id: H1, H2, ... // - description: What might be wrong // - testable_condition: What to log // - logging_point: Where to add instrumentation // - evidence_criteria: What confirms/rejects it return hypotheses } Save to hypotheses.json : { "iteration" : 1 , "timestamp" : "2025-01-21T10:00:00+08:00" , "hypotheses" : [ { "id" : "H1" , "description" : "Data structure mismatch - expected key not present" , "testable_condition" : "Check if target key exists in dict" , "logging_point" : "file.py:func:42" , "evidence_criteria" : { "confirm" : "data shows missing key" , "reject" : "key exists with valid value" } , "likelihood" : 1 , "status" : "pending" } ] } Step 1.4: Add NDJSON Instrumentation For each hypothesis, add logging at the specified location: Python template :

region debug [H{n}]

try : import json , time _dbg = { "sid" : "{sessionId}" , "hid" : "H{n}" , "loc" : "{file}:{line}" , "msg" : "{testable_condition}" , "data" : {

Capture relevant values here

} , "ts" : int ( time . time ( ) * 1000 ) } with open ( r"{debugLogPath}" , "a" , encoding = "utf-8" ) as _f : _f . write ( json . dumps ( _dbg , ensure_ascii = False ) + "\n" ) except : pass

endregion

JavaScript/TypeScript template : // region debug [H{n}] try { require ( 'fs' ) . appendFileSync ( "{debugLogPath}" , JSON . stringify ( { sid : "{sessionId}" , hid : "H{n}" , loc : "{file}:{line}" , msg : "{testable_condition}" , data : { / Capture relevant values / } , ts : Date . now ( ) } ) + "\n" ) ; } catch ( _ ) { } // endregion Step 1.5: Output to User

Hypotheses Generated

Based on error "$BUG", generated {n} hypotheses: {hypotheses.map(h => `

${h.id}: ${h.description}

Logging at: ${h.logging_point}
Testing: ${h.testable_condition}
Evidence to confirm: ${h.evidence_criteria.confirm}
Evidence to reject: ${h.evidence_criteria.reject} `).join('')} Debug log: ${debugLogPath} Next: Run reproduction steps, then come back for analysis. Analyze Mode Step 2.1: Parse Debug Log // Parse NDJSON log const entries = Read ( debugLogPath ) . split ( '\n' ) . filter ( l => l . trim ( ) ) . map ( l => JSON . parse ( l ) ) // Group by hypothesis const byHypothesis = groupBy ( entries , 'hid' ) // Validate each hypothesis for ( const [ hid , logs ] of Object . entries ( byHypothesis ) ) { const hypothesis = hypotheses . find ( h => h . id === hid ) const latestLog = logs [ logs . length - 1 ] // Check if evidence confirms or rejects hypothesis const verdict = evaluateEvidence ( hypothesis , latestLog . data ) // Returns: 'confirmed' | 'rejected' | 'inconclusive' } Step 2.2: Analyze Evidence and Correct Understanding Review the debug log and evaluate each hypothesis: Parse all log entries Group by hypothesis ID Compare evidence against expected criteria Determine verdict: confirmed | rejected | inconclusive Identify incorrect assumptions from previous understanding Generate corrections Step 2.3: Update Understanding with Corrections Append new iteration to understanding.md :

Iteration ${n} - Evidence Analysis (${timestamp})

Log Analysis Results
${results.map(r => `
**
${r.id}
**: ${r.verdict.toUpperCase()}

Evidence: ${JSON.stringify(r.evidence)}
Reasoning: ${r.reason} `).join('\n')}

Corrected Understanding Previous misunderstandings identified and corrected: ${corrections.map(c => - ~~ ${c.wrong} ~~ → ${c.corrected} - Why wrong: ${c.reason} - Evidence: ${c.evidence}).join('\n')}

New Insights ${newInsights.join('\n- ')} ${confirmedHypothesis ? `

Root Cause Identified
**
${confirmedHypothesis.id}
**: ${confirmedHypothesis.description} Evidence supporting this conclusion: ${confirmedHypothesis.supportingEvidence} :

Next Steps ${nextSteps} `}

Current Consolidated Understanding (Updated) ${consolidatedUnderstanding} Step 2.4: Update hypotheses.json { "iteration" : 2 , "timestamp" : "2025-01-21T10:15:00+08:00" , "hypotheses" : [ { "id" : "H1" , "status" : "rejected" , "verdict_reason" : "Evidence shows key exists with valid value" , "evidence" : { ... } } , { "id" : "H2" , "status" : "confirmed" , "verdict_reason" : "Log data confirms timing issue" , "evidence" : { ... } } ] , "corrections" : [ { "wrong_assumption" : "..." , "corrected_to" : "..." , "reason" : "..." } ] } Fix & Verification Step 3.1: Apply Fix Based on confirmed hypothesis, implement the fix in the affected files. Step 3.2: Document Resolution Append to understanding.md :

Iteration ${n} - Resolution (${timestamp})

Fix Applied

Modified files: ${modifiedFiles.join(', ')}

Fix description: ${fixDescription}

Root cause addressed: ${rootCause}

Verification Results ${verificationResults}

Lessons Learned What we learned from this debugging session: 1. ${lesson1} 2. ${lesson2} 3. ${lesson3}

Key Insights for Future

${insight1}

${insight2} Step 3.3: Cleanup Remove debug instrumentation by searching for region markers: const instrumentedFiles = Grep ( { pattern : "# region debug|// region debug" , output_mode : "files_with_matches" } ) for ( const file of instrumentedFiles ) { // Remove content between region markers removeDebugRegions ( file ) } Session Folder Structure {projectRoot}/.workflow/.debug/DBG-{slug}-{date}/ ├── debug.log # NDJSON log (execution evidence) ├── understanding.md # Exploration timeline + consolidated understanding └── hypotheses.json # Hypothesis history with verdicts Understanding Document Template

Understanding Document

Session ID

DBG-xxx-2025-01-21

Bug Description

[original description]
**
Started
**: 2025-01-21T10:00:00+08:00

Exploration Timeline

Iteration 1 - Initial Exploration (2025-01-21 10:00)

Current Understanding ...

Evidence from Code Search ...

Hypotheses Generated ...

Iteration 2 - Evidence Analysis (2025-01-21 10:15)

Log Analysis Results ...

Corrected Understanding

~~ [wrong] ~~ → [corrected]

Analysis Results ...

Current Consolidated Understanding

What We Know

[valid understanding points]

What Was Disproven

~~ [disproven assumptions] ~~

Current Investigation Focus [current focus]

Remaining Questions

[open questions]

Debug Log Format (NDJSON)

Each line is a JSON object:

{

"sid"

:

"DBG-xxx-2025-01-21"

,

"hid"

:

"H1"

,

"loc"

:

"file.py:func:42"

,

"msg"

:

"Check dict keys"

,

"data"

:

{

"keys"

:

[

"a"

,

"b"

]

,

"target"

:

"c"

,

"found"

:

false

}

,

"ts"

:

1734567890123

}

Field

Description

sid

Session ID

hid

Hypothesis ID (H1, H2, ...)

loc

Code location

msg

What's being tested

data

Captured values

ts

Timestamp (ms)

Iteration Flow

First Call (BUG="error"):

├─ No session exists → Explore mode

├─ Extract error keywords, search codebase

├─ Document initial understanding in understanding.md

├─ Generate hypotheses

├─ Add logging instrumentation

└─ Await user reproduction

After Reproduction (BUG="error"):

├─ Session exists + debug.log has content → Analyze mode

├─ Parse log, evaluate hypotheses

├─ Update understanding.md with:

│ ├─ Evidence analysis results

│ ├─ Corrected misunderstandings (strikethrough)

│ ├─ New insights

│ └─ Updated consolidated understanding

├─ Update hypotheses.json with verdicts

└─ Decision:

├─ Confirmed → Fix → Document resolution

├─ Inconclusive → Add logging, document next steps

└─ All rejected → Assisted new hypotheses

Output:

├─ {projectRoot}/.workflow/.debug/DBG-{slug}-{date}/debug.log

├─ {projectRoot}/.workflow/.debug/DBG-{slug}-{date}/understanding.md (evolving document)

└─ {projectRoot}/.workflow/.debug/DBG-{slug}-{date}/hypotheses.json (history)

Error Handling

Situation

Action

Empty debug.log

Verify reproduction triggered the code path

All hypotheses rejected

Generate new hypotheses based on disproven assumptions

Fix doesn't work

Document failed fix attempt, iterate with refined understanding

>5 iterations

Review consolidated understanding, escalate with full context

Understanding too long

Consolidate aggressively, archive old iterations to separate file

Consolidation Rules

When updating "Current Consolidated Understanding":

Simplify disproven items

Move to "What Was Disproven" with single-line summary

Keep valid insights

Promote confirmed findings to "What We Know"

Avoid duplication

Don't repeat timeline details in consolidated section

Focus on current state

What do we know NOW, not the journey
Preserve key corrections: Keep important wrong→right transformations for learning Bad (cluttered) :

Current Consolidated Understanding In iteration 1 we thought X, but in iteration 2 we found Y, then in iteration 3... Also we checked A and found B, and then we checked C... Good (consolidated) :

Current Consolidated Understanding

What We Know

Error occurs during runtime update, not initialization

Config value is None (not missing key)

What Was Disproven

~~ Initialization error ~~ (Timing evidence) - ~~ Missing key hypothesis ~~ (Key exists)

Current Investigation Focus
Why is config value None during update?
Key Features
Feature
Description
NDJSON logging
Structured debug log with hypothesis tracking
Hypothesis generation
Analysis-assisted hypothesis creation
Exploration documentation
understanding.md with timeline
Understanding evolution
Timeline + corrections tracking
Error correction
Strikethrough + reasoning for wrong assumptions
Consolidated learning
Current understanding section
Hypothesis history
hypotheses.json with verdicts
Analysis validation
At key decision points
When to Use
Best suited for:
Complex bugs requiring multiple investigation rounds
Learning from debugging process is valuable
Team needs to understand debugging rationale
Bug might recur, documentation helps prevention
Now execute the debug-with-file workflow for bug: $BUG

安装

Next Steps

Generate testable hypotheses

Add instrumentation

Await reproduction

region debug [H{n}]

Capture relevant values here

endregion

Hypotheses Generated

${h.id}: ${h.description}

${r.verdict.toUpperCase()}

Evidence: ${JSON.stringify(r.evidence)}

Fix Applied

Modified files: ${modifiedFiles.join(', ')}

Fix description: ${fixDescription}

Key Insights for Future

${insight1}

Corrected Understanding

What We Know

What Was Disproven

Remaining Questions

What We Know

Error occurs during runtime update, not initialization

What Was Disproven