build-small-hackathon/trace-field-notes

1# Agent Trace Narrative Analyzer — Hackathon App Design Doc2 3版本：v0.24目標平台：Hugging Face Space / Gradio App5目標 hackathon：Build Small Hackathon 20266主要使用者：使用 Codex、Claude Code、Pi Agent 等 coding agent 的開發者，想理解「agent 是怎麼卡住、繞路、恢復、收束」的人。7 8---9 10## 1. 一句話概念11 12**Agent Trace Narrative Analyzer** 是一個 Gradio App：使用者上傳 Codex / Claude Code / Pi Agent 的 session log（JSONL），App 不分析 tool-call 細節，而是只讀 agent 自己寫出的 progress / assistant messages，抽出「困難片段」並產生一份可讀的 qualitative report：13 14- agent 遇到哪些困難？15- 它怎麼理解困難？16- 它有沒有繞路或改變策略？17- 它用了什麼解決方式？18- 它花了多久從困難走到收束？如果 trace 有 timestamp。19- 它最後是有把限制講清楚，還是太快宣稱完成？20 21這個產品的核心不是 benchmark，也不是 tool-use telemetry，而是 **coding agent 的「敘事性問題解決歷程」分析**。22 23---24 25## 2. Hackathon fit26 27Build Small Hackathon 的精神是「用 ≤32B 的小模型，做小而真實、有趣、可展示的東西」。官方規則包含：28 29- small models only：模型總參數必須 ≤32B。30- 必須是 Gradio app，並部署成 Hugging Face Space。31- 需要 short demo video 與 social-media post。32- Backyard AI track 重視：問題是否 specific and real、是否真的有人用、是否誠實符合 small-model constraint、Gradio app polish。33- Thousand Token Wood track 重視 delight / originality / AI 是否是 load-bearing。34- Bonus badges 中有一個與 trace 很貼近：**Sharing is Caring / Open trace**，也有 **Field Notes** 可透過 blog/report 加分。35 36模型敘事建議：使用 `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` 作為主模型。它的 total parameters 是 30B，符合 ≤32B 上限；同時它是 MoE，每 token active parameters 約 3.5B，很適合用來講「small active compute, agentic analysis」的 hackathon 故事。37 38本 app 建議定位在 **Backyard AI**：服務一群很具體的人，也就是正在用 coding agents 的 builder / hackathon participant / developer。他們真實會遇到的問題是：agent session 很長，最後 patch 對不對不容易說清楚，但更難的是理解「agent 到底怎麼走到這裡」。39 40可順手爭取的 badges / awards：41 42- **Best Agent**：如果 app 本身也提供 agent-callable workflow。43- **Sharing is Caring / Open trace**：提供「如何把已 redacted traces 分享到 Hub」的教學或範例。44- **Field Notes**：用 app 產出的 reports 寫一篇短文，展示從 traces 裡看見的 agent behavior patterns。45- **Off-Brand / Custom UI**：如果前端視覺做得像「trail map / field notebook」。46 47---48 49## 3. 產品名稱候選50 511. **Trace Field Notes**522. **Agent Detour Map**533. **Trace Cartographer**544. **Agent Recovery Lens**555. **Small Trace, Big Journey**56 57建議用：**Trace Field Notes**。它符合 hackathon 的 woodland / field-notes 氣質，也強調 qualitative analysis，而不是 leaderboard。58 59---60 61## 4. 使用者體驗流程62 63### 4.1 首頁結構64 65首頁第一眼應該看到：66 67**Hero title**68 69> Trace Field Notes70> See how your coding agent got stuck, detoured, recovered, and claimed success.71 72**Short explanation**73 74> Upload a Codex / Claude Code / Pi Agent JSONL session log. This app analyzes the agent's narrated progress messages, not raw tool telemetry, and turns the session into a qualitative map of difficulties, detours, recovery patterns, and outcome claims.75 76**Privacy warning**77 78> Agent traces may include prompts, tool inputs, command output, local paths, screenshots, secrets, private code, and personal data. Review and redact before uploading or sharing publicly.79 80**How to find your session log**81 82官方 HF Agent Traces docs 目前列出這些本機路徑：83 84| Agent | Local session directory |85|---|---|86| Claude Code | `~/.claude/projects` |87| Codex | `~/.codex/sessions` |88| Pi Agent | `~/.pi/agent/sessions` |89 90首頁要提供 copyable instructions：91 92```bash93# Codex94ls ~/.codex/sessions95 96# Claude Code97ls ~/.claude/projects98 99# Pi Agent100ls ~/.pi/agent/sessions101```102 103**Upload area**104 105- File input: `.jsonl`, `.json`, `.txt`, `.log`106- Checkbox: `Redact likely secrets before analysis`，預設 on107- Checkbox: `Include user prompts as context`，預設 on108- Checkbox: `Ignore tool call contents`，預設 on and locked for MVP109- Button: `Analyze my trace`110 111**Agent-callable area**112 113> Using Codex or Claude Code? Point your agent at this Space's `agents.md`. It can find your local session log, upload it, and call the analysis endpoint for you.114 115顯示一段 prompt：116 117```text118Find my latest coding-agent session log, review it for secrets, then use this Space via its agents.md endpoint to upload the JSONL file and request a narrative difficulty analysis. Do not publish the raw trace. Return the report and any caveats.119 120Space agents.md:121https://huggingface.co/spaces/<namespace>/<space-name>/agents.md122```123 124---125 126## 5. Agent-callable workflow via agents.md127 128Hugging Face / Gradio 會替每個 Gradio Space 提供 plain-text `agents.md` endpoint。coding agents 可以讀取它來取得：129 130- API schema URL131- call endpoint132- poll endpoint133- file-upload instructions134- auth hint135 136所以 MVP 不需要另外實作 custom API。只要 Gradio function 的輸入輸出定義清楚，`agents.md` 就會讓 Codex / Claude Code 之類的工具知道如何呼叫。137 138### 5.1 Gradio function 建議139 140主要 endpoint：141 142```python143def analyze_trace(144    trace_file,145    include_user_context: bool = True,146    redact_secrets: bool = True,147    ignore_tool_calls: bool = True,148    report_style: str = "field_notes",149):150    """151    Input: Codex / Claude Code / Pi Agent JSONL session log.152    Output: Markdown report + structured episode JSON + downloadable redacted narrative text.153    """154```155 156回傳：157 158```python159return report_markdown, episode_json, redacted_narrative_file160```161 162### 5.2 在 UI 中提供給 Codex / Claude Code 的 prompt163 164```text165Use this Space as a tool.1661. Read: https://huggingface.co/spaces/<namespace>/<space-name>/agents.md1672. Find my latest local agent session log:168   - Codex: ~/.codex/sessions169   - Claude Code: ~/.claude/projects170   - Pi Agent: ~/.pi/agent/sessions1713. Review and redact secrets or private code before upload.1724. Upload the JSONL to the Space.1735. Ask for narrative difficulty analysis.1746. Return the report. Do not publish the raw trace.175```176 177---178 179## 6. What the app analyzes180 181本 app 不以 tool calls 為主要分析對象。它只使用：182 183- assistant / agent narrative messages184- visible progress messages185- planning messages186- self-reported problems187- self-reported strategy shifts188- final summary / outcome claims189- optional user prompts as context190 191MVP 預設忽略：192 193- raw tool inputs194- raw tool outputs195- command stdout / stderr196- full file diffs197- private code snippets inside tool outputs198 199重要措辭：200 201> We analyze the **agent's narrated process**, not its hidden internal reasoning and not the complete tool telemetry.202 203這樣比較安全，也比較符合質性分析：我們不是宣稱知道 agent 真正怎麼想，只分析它明確寫出來的問題處理敘事。204 205---206 207## 7. 核心分析單位：Difficulty Episode208 209不要以每個 message 或每個 tool call 為單位。分析單位是：210 211> 一段 agent 原本想做某件事，遇到阻礙，重新評估，改變或維持策略，嘗試處理，最後收束或未收束的片段。212 213核心流程：214 215```text216Initial intention217→ Reported difficulty218→ Appraisal219→ Strategy shift / detour220→ Attempted resolution221→ Outcome claim222```223 224中文：225 226```text227原本意圖228→ 遇到的困難229→ 對困難的判斷230→ 策略轉換 / 繞路231→ 解決嘗試232→ 結果宣稱233```234 235---236 237## 8. Codebook238 239### 8.1 Difficulty Type240 241| Code | 說明 |242|---|---|243| `requirement_uncertainty` | 需求、規格、使用者意圖不清楚 |244| `localization_difficulty` | 不知道問題在哪個模組 / 檔案 / 函式 |245| `architecture_complexity` | 發現系統結構、依賴或 shared component 比預期複雜 |246| `implementation_difficulty` | 知道方向但不確定怎麼實作 |247| `compatibility_risk` | 擔心改 A 會破壞 B，或需要保留既有行為 |248| `verification_difficulty` | 不知道怎麼確認修好了 |249| `environment_blocker` | 測試、依賴、環境、權限等問題 |250| `insufficient_context` | agent 表示需要更多上下文 |251| `conflicting_assumptions` | 原本假設和新資訊衝突 |252| `unknown` | 無法判斷 |253 254### 8.2 Appraisal255 256| Code | 說明 |257|---|---|258| `local_fix_possible` | agent 把問題視為可局部修補 |259| `needs_more_context` | agent 認為需要更多資訊 |260| `initial_hypothesis_wrong` | agent 承認原本假設可能錯 |261| `risk_is_higher_than_expected` | agent 意識到副作用或風險較高 |262| `scope_too_large` | agent 認為原方案太大，需縮小 |263| `needs_alternative_path` | agent 開始尋找替代路徑 |264| `cannot_reliably_verify` | agent 承認無法可靠驗證 |265| `task_boundary_unclear` | agent 認為任務邊界不清 |266 267### 8.3 Strategy Shift / Detour Type268 269| Code | 說明 |270|---|---|271| `direct_continuation` | 沿用原策略 |272| `decomposition` | 拆解問題 |273| `scope_narrowing` | 縮小修改或分析範圍 |274| `alternative_path` | 換一條路處理 |275| `workaround` | 不解根因，先繞過 |276| `rollback_or_reversal` | 放棄前一方向或撤回 |277| `hypothesis_switch` | 換一個問題假設 |278| `verification_shift` | 改變驗證方式 |279| `ask_or_defer` | 請求使用者資訊或暫停判斷 |280| `premature_closure` | 沒處理完就收束 |281 282### 8.4 Resolution Mode283 284| Code | 說明 |285|---|---|286| `information_gathering` | 透過更多上下文解決 |287| `problem_reframing` | 重新定義問題 |288| `minimal_patch` | 做最小修改 |289| `structural_change` | 採用較大結構變更 |290| `defensive_handling` | 加 fallback、guard、error handling |291| `alternative_implementation` | 換一種實作方式 |292| `goal_reduction` | 降低目標或只解部分問題 |293| `explicit_limitation` | 明確承認限制 |294| `narrative_rationalization` | 用流暢敘事合理化，但未見真策略轉換 |295 296### 8.5 Recovery Pattern297 298| Code | 說明 |299|---|---|300| `smooth_recovery` | 快速理解困難並恢復推進 |301| `iterative_recovery` | 經過幾次嘗試逐步接近 |302| `detour_recovery` | 繞路後恢復 |303| `partial_recovery` | 解了一部分，保留限制 |304| `failed_recovery` | 嘗試但沒有走出困境 |305| `avoidant_recovery` | 跳過困難，改做旁邊的事 |306| `overconfident_recovery` | 困難未清楚解決但宣稱成功 |307| `reflective_recovery` | 明確說明原假設錯在哪並修正 |308 309### 8.6 Outcome Claim310 311| Code | 說明 |312|---|---|313| `resolved_with_confidence` | 明確宣稱已解決 |314| `resolved_with_caveat` | 宣稱解決，但有保留條件 |315| `partially_resolved` | 說明只完成一部分 |316| `not_resolved` | 承認未解決 |317| `needs_verification` | 說還需要測試 / 確認 |318| `uncertain_but_proceeding` | 不確定但繼續 |319| `premature_success_claim` | 證據或敘事不足卻宣稱完成 |320 321---322 323## 9. Structured Episode Schema324 325LLM 或 parser 最終應輸出以下 JSON：326 327```json328{329  "trace_title": "string",330  "agent_type_guess": "codex | claude_code | pi | unknown",331  "analysis_scope": "assistant narrative messages only",332  "privacy_notes": ["string"],333  "episodes": [334    {335      "episode_id": "E01",336      "title": "string",337      "message_span": {338        "start_index": 0,339        "end_index": 3,340        "start_time": "optional timestamp",341        "end_time": "optional timestamp",342        "duration_label": "e.g. 4m 20s / unknown"343      },344      "initial_intention": "string",345      "reported_difficulty": "string",346      "difficulty_type": "one code from codebook",347      "appraisal": "one code from codebook",348      "strategy_before": "string",349      "strategy_after": "string",350      "detour_type": "one code from codebook",351      "resolution_mode": "one code from codebook",352      "recovery_pattern": "one code from codebook",353      "outcome_claim": "one code from codebook",354      "productive_detour": "yes | no | mixed | unknown",355      "evidence_quotes": [356        "short quote from agent message, <= 30 words"357      ],358      "analyst_memo": "string"359    }360  ],361  "overall_patterns": {362    "difficulty_style": "string",363    "detour_style": "string",364    "recovery_style": "string",365    "risk_or_caveat": "string"366  }367}368```369 370---371 372## 10. Report design373 374分析結果頁面不要像 dashboard metrics，而要像「field report」。建議分成 6 個區塊。375 376### 10.1 Executive Summary377 378短短 5–8 句：379 380- 這個 trace 的主線是什麼？381- agent 主要遇到哪些困難？382- 它的恢復方式偏哪一種？383- 有沒有明顯繞路？384- 最後宣稱是否保守、清楚、有 caveat？385 386### 10.2 Journey Timeline387 388用時間線或 cards 顯示每個 difficulty episode：389 390```text391E01 — Initial misunderstanding392Intention: ...393Difficulty: ...394Shift: ...395Resolution: ...396Outcome claim: ...397Duration: 3m 12s / unknown398```399 400視覺建議：401 402- green：smooth / reflective recovery403- yellow：partial / uncertain recovery404- red：failed / overconfident / premature closure405- blue：productive detour406- gray：unknown / no timestamp407 408### 10.3 Difficulty Map409 410不是量化長條圖，而是 thematic clusters：411 412```text413Main difficulties observed:414- Localization difficulty: E01, E03415- Compatibility risk: E02416- Verification difficulty: E04417```418 419每個 cluster 下方附 1–2 句解釋與 quote。420 421### 10.4 Detour Analysis422 423重點回答使用者真正關心的問題：424 425> 它有沒有繞路？這個繞路是有效探索，還是無效遊走？426 427可分為：428 429- Productive detour：原路不通 → 有新假設 → 縮小問題 → 繼續接近目標。430- Unproductive wandering：換方向但沒有新假設，問題越看越散。431- Workaround：不解根因，但有意識地降低風險或達成局部目標。432 433### 10.5 Recovery Pattern434 435輸出一段「恢復風格」：436 437> This agent tends to recover by reframing the problem and narrowing scope. It rarely asks for help, and it sometimes closes the loop before verification is fully established.438 439### 10.6 Outcome Claim Audit440 441不是驗證程式碼是否真的正確，而是檢查它怎麼說「我完成了」：442 443- 有沒有 caveat？444- 有沒有承認未驗證？445- 有沒有把 workaround 包裝成 root-cause fix？446- 有沒有過早成功宣稱？447 448---449 450## 11. Small-model analysis pipeline451 452因為 hackathon 限制 small models，MVP 應採取「small model + 結構化 prompt + 分段處理」而不是一次丟完整 trace。模型選型以 `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` 為主：它是 30B total parameters、約 3.5B active parameters per token 的 MoE 模型，剛好符合 Build Small Hackathon 的 ≤32B total-parameter 限制，且定位適合 coding / agentic / instruction-following 場景。453 454### 11.1 Pipeline455 456```text457Upload file458→ Parse JSONL459→ Extract narrative messages460→ Redact likely secrets461→ Chunk into windows462→ LLM pass 1: identify candidate difficulty episodes463→ LLM pass 2: classify each episode with codebook464→ LLM pass 3: synthesize field report465→ Render UI + export JSON/Markdown466```467 468### 11.2 Fallback heuristic469 470如果模型不可用或輸出 JSON 壞掉，使用 rule-based fallback：471 472- difficulty signals：`failed`, `error`, `not working`, `issue`, `problem`, `can't`, `cannot`, `unclear`, `ambiguous`, `however`, `instead`, `safer`, `fallback`, `retry`, `try another`, `need to`, `I should`, `looks like`473- strategy shift signals：`instead`, `rather than`, `safer approach`, `I'll try`, `switch`, `fallback`, `alternative`, `narrow`, `simpler`, `roll back`474- outcome signals：`done`, `fixed`, `resolved`, `should`, `verified`, `could not`, `need to verify`, `not able`475 476Fallback 只需要產生粗略 cards，不需要完美分類。477 478### 11.3 Model selection479 480**Primary / showcase model**481 482- Model: `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16`483- Why it fits:484  - 30B total parameters, under the hackathon's ≤32B cap.485  - MoE architecture with about 3.5B active parameters per token, so the active compute is closer to a small model than to a dense 30B model.486  - Designed for English, coding languages, reasoning, chat, agent systems, RAG, and instruction-following tasks.487  - Strong conceptual fit: the app analyzes coding-agent narratives, so using an agentic / coding-oriented small model is part of the story.488 489**Runtime target**490 491- Deploy as a Hugging Face Gradio Space using **ZeroGPU**.492- Use `@spaces.GPU(size="xlarge", duration=...)` for the analysis function.493- Reason: BF16 30B weights are roughly 60GB before KV cache and runtime overhead, so ZeroGPU `large` may be tight; `xlarge` is safer for the demo.494- Caveat: ZeroGPU `xlarge` consumes 2× quota and can have longer queues. The app should therefore support a quick / fallback path.495 496**Fallback / quick mode**497 498Keep the implementation model-pluggable:499 500- Fallback model: `Qwen/Qwen3.5-9B`501  - Use when ZeroGPU queue is long, traces are short, or demo latency matters more than analysis depth.502- Rule-based fallback:503  - Always keep the heuristic path in `11.2`, so the app can still produce rough episode cards if the model fails or JSON parsing breaks.504 505**Language policy**506 507- Trace analysis should be English-first, because most coding-agent session messages are English and Nemotron 3 Nano's listed supported languages do not include Chinese.508- The UI can be bilingual.509- If Traditional Chinese output is required, prefer this pipeline:510 511```text512Nemotron → structured English JSON analysis → template-rendered Traditional Chinese summary513```514 515Do not rely on the main model to produce polished Traditional Chinese in the MVP.516 517**Important prompting constraint**518 519Do not ask the model to reveal hidden reasoning. The prompts should request structured fields and short evidence quotes from visible agent messages only.520 521---522 523## 12. LLM prompt templates524 525### 12.1 Episode extraction prompt526 527```text528You are analyzing a coding agent session log.529Only analyze the agent's visible narrative messages.530Do not infer hidden thoughts. Do not analyze raw tool outputs.531 532Task:533Identify difficulty episodes.534A difficulty episode is a span where the agent:5351. states or implies an intention,5362. encounters uncertainty, failure, risk, ambiguity, or blockage,5373. appraises the situation,5384. changes or maintains strategy,5395. attempts a resolution,5406. makes an outcome claim.541 542Return JSON only using this schema:543{ ...schema... }544 545Messages:546{messages}547```548 549### 12.2 Episode classification prompt550 551```text552Classify each difficulty episode using the codebook.553Prefer "unknown" if the evidence is weak.554Use short direct quotes as evidence.555Do not claim the agent actually understood something; say the agent reported, framed, claimed, or presented.556 557Codebook:558{codebook}559 560Episodes:561{episodes}562```563 564### 12.3 Report synthesis prompt565 566```text567Write a concise field-note style report for a developer who wants to understand how their coding agent handled difficulty.568Avoid quantitative leaderboard language.569Focus on:570- What the agent struggled with571- How it appraised the problem572- Whether it took productive detours573- How it recovered574- How it claimed completion575- Caveats and uncertainty576 577Use headings and episode IDs.578```579 580---581 582## 13. Privacy and safety design583 584### 13.1 Warning copy585 586Use this exact warning near upload:587 588> Agent traces can contain prompts, tool inputs, command outputs, local file paths, screenshots, secrets, private source code, and personal data. Redact before uploading. This app analyzes only visible agent narrative messages by default and does not need raw tool outputs.589 590### 13.2 Redaction MVP591 592Regex redactions:593 594- API keys / tokens common patterns595- `Authorization: Bearer ...`596- GitHub tokens: `ghp_`, `github_pat_`597- OpenAI / HF tokens if recognizable598- emails599- absolute local paths, optional600- URLs with query strings, optional601- long base64-like strings602 603### 13.3 Storage policy604 605MVP should default to:606 607- Do not persist uploaded traces.608- Delete temp files after analysis if feasible.609- Allow user to download redacted narrative only.610- Do not publish trace unless user explicitly chooses to.611 612---613 614## 14. Implementation outline615 616### 14.1 Suggested file structure617 618```text619.620├── app.py621├── analyzer.py622├── parser.py623├── redaction.py624├── prompts.py625├── schemas.py626├── report_renderer.py627├── requirements.txt628├── README.md629└── examples/630    └── sample_trace_redacted.jsonl631```632 633### 14.2 `parser.py`634 635Responsibilities:636 637- Load `.jsonl`, `.json`, `.txt`.638- Detect likely agent type.639- Extract role, timestamp, content.640- Keep assistant narrative messages.641- Optionally include user prompts as context.642- Skip tool call contents by default.643 644Pseudo-code:645 646```python647def parse_trace(path, include_user_context=True, ignore_tool_calls=True):648    records = load_jsonl_or_text(path)649    messages = []650    for record in records:651        msg = normalize_record(record)652        if msg.role == "assistant" and msg.text:653            messages.append(msg)654        elif include_user_context and msg.role == "user":655            messages.append(msg)656    return messages657```658 659### 14.3 `analyzer.py`660 661Responsibilities:662 663- Chunk messages.664- Call the primary model (`nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16`) through ZeroGPU, or call the fallback model / heuristic path.665- Validate JSON.666- Fall back to heuristics.667- Merge overlapping episodes.668 669### 14.4 `report_renderer.py`670 671Responsibilities:672 673- Render markdown report.674- Render episode cards for Gradio.675- Export JSON.676 677### 14.5 `app.py`678 679Gradio Blocks layout:680 681```python682with gr.Blocks(title="Trace Field Notes") as demo:683    gr.Markdown(HERO_MD)684    with gr.Row():685        file = gr.File(label="Upload your agent session log")686        options = ...687    analyze_btn = gr.Button("Analyze my trace")688    report = gr.Markdown()689    episodes = gr.JSON()690    download = gr.File(label="Download redacted narrative")691```692 693### 14.6 `model_runtime.py`694 695Responsibilities:696 697- Load the primary model at module root level for ZeroGPU compatibility.698- Wrap the expensive analysis function with `@spaces.GPU(size="xlarge", duration=...)`.699- Provide a fallback path if model loading, generation, or JSON parsing fails.700 701Sketch:702 703```python704import spaces705import torch706from transformers import AutoModelForCausalLM, AutoTokenizer707 708PRIMARY_MODEL_ID = "nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16"709FALLBACK_MODEL_ID = "Qwen/Qwen3.5-9B"710 711tokenizer = AutoTokenizer.from_pretrained(712    PRIMARY_MODEL_ID,713    trust_remote_code=True,714)715model = AutoModelForCausalLM.from_pretrained(716    PRIMARY_MODEL_ID,717    torch_dtype=torch.bfloat16,718    trust_remote_code=True,719).to("cuda")720 721@spaces.GPU(size="xlarge", duration=180)722def run_primary_model(messages, max_new_tokens=2048):723    # Build chat template, generate JSON, validate downstream.724    ...725```726 727Implementation note: this is a sketch, not guaranteed final code. Codex should test model loading on the actual Space and adjust memory settings, max tokens, or fallback behavior as needed.728 729---730 731## 15. MVP scope732 733### Must have734 735- Gradio Space UI.736- File upload.737- Clear tutorial for Codex / Claude Code / Pi local session folders.738- Privacy warning + basic redaction.739- Ignore tool-call contents by default.740- Extract assistant narrative messages.741- Identify difficulty episodes.742- Classify difficulty / appraisal / detour / resolution / recovery / outcome claim.743- Render readable field-note report.744- Export structured JSON.745- Provide copyable agents.md prompt for Codex / Claude Code.746 747### Should have748 749- Sample trace button.750- Download report as Markdown.751- Duration labels if timestamps exist.752- “Productive detour vs wandering” section.753- “Completion claim audit” section.754 755### Nice to have756 757- Compare two traces side-by-side.758- Load public HF dataset / bucket trace URL.759- Share redacted analysis report to dataset or gist.760- Custom visual timeline.761- Blog/report generator for Field Notes badge.762 763---764 765## 16. Demo script766 7671. Open the Space.7682. Show the hero: “upload an agent session log; see how the agent got stuck and recovered.”7693. Show where traces live:770   - Codex: `~/.codex/sessions`771   - Claude Code: `~/.claude/projects`7724. Upload a redacted `.jsonl` trace.7735. App shows:774   - Executive summary775   - Timeline of difficulty episodes776   - Detour analysis777   - Recovery pattern778   - Outcome claim audit7796. Show the copyable prompt for Codex / Claude Code to call the Space through `agents.md`.7807. End with the core message:781 782> We do not just ask whether an agent succeeded. We look at how it handled difficulty.783 784---785 786## 17. Suggested README pitch787 788```markdown789# Trace Field Notes790 791Trace Field Notes turns coding-agent session logs into qualitative field reports.792 793Upload a Codex, Claude Code, or Pi Agent JSONL trace. The app ignores raw tool telemetry by default and analyzes only the agent's visible narrative messages: what it planned, where it got stuck, how it detoured, how it recovered, and how it claimed completion.794 795Built for the Build Small Hackathon with NVIDIA Nemotron 3 Nano 30B-A3B under the 32B total-parameter limit and deployed as a Gradio Space on Hugging Face ZeroGPU.796```797 798---799 800## 18. Source references801 802- Build Small Hackathon page: https://huggingface.co/build-small-hackathon803- NVIDIA Nemotron 3 Nano 30B-A3B BF16 model card: https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16804- Hugging Face ZeroGPU docs: https://huggingface.co/docs/hub/en/spaces-zerogpu805- Hugging Face Agent Traces docs: https://huggingface.co/docs/hub/agent-traces806- Hugging Face Spaces as Agent Tools docs: https://huggingface.co/docs/hub/spaces-agents807- Hugging Face changelog for Spaces agents.md: https://huggingface.co/changelog/spaces-agents-md808 809---810 811## 19. Codex handoff prompt812 813Use this prompt to ask Codex to implement the MVP:814 815```text816Build a Hugging Face Space Gradio app called Trace Field Notes.817 818Read the design doc in this repository. Implement the MVP only:819- app.py Gradio Blocks UI820- upload .jsonl/.json/.txt/.log821- parse Codex / Claude Code / Pi Agent session logs822- extract only assistant narrative messages and optional user prompts823- ignore tool-call contents by default824- redact likely secrets before analysis825- identify difficulty episodes826- classify episodes using the provided codebook827- render a field-note style report828- export structured JSON and downloadable Markdown829 830Do not implement leaderboard metrics. Do not analyze raw tool-call telemetry. The product is qualitative: difficulty, detour, recovery, and outcome-claim analysis.831 832Keep the code simple and hackathon-ready. Use `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` as the primary model on Hugging Face ZeroGPU xlarge, with `Qwen/Qwen3.5-9B` or the heuristic path as fallback so the app still works in demo mode.833```834