hamster-thread-diagnostics
Diagnose chat thread issues from a thread_id and a user-provided symptom. Use when the user reports a misbehaving thread (missing diff preview, duplicate spawns, hallucinated failures, child threads not opening, missing Accept buttons, etc.). Walks the parent + child threads, tool_calls, participants, and relevant code paths to produce a root-cause summary and a concrete fix plan.
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- hamster-thread-diagnostics
- version
- 1.0.0
- description
- Diagnose chat thread issues from a thread_id and a user-provided symptom. Use when the user reports a misbehaving thread (missing diff preview, duplicate spawns, hallucinated failures, child threads not opening, missing Accept buttons, etc.). Walks the parent + child threads, tool_calls, participants, and relevant code paths to produce a root-cause summary and a concrete fix plan.
03 SKILL.md 正文
Hamster Thread Diagnostics
Overview
The chat system has many moving pieces — Supabase tables, scoped Zustand stores, the conductor agent, spawn flows, realtime subscriptions, and the editor — and bugs usually live at the seams. This skill encodes the workflow for tracing a reported issue back to its root cause given a thread_id and a description of what the user observed.
Required inputs
- A
thread_id(UUID) — the parent thread the user was in when the issue occurred. - A symptom description — what the user did, what they saw, what they expected. The more specific the better (e.g. "I see suggested edits in the spawned thread but no Accept button in the editor" beats "the chat is broken").
If only one is provided, ask for the other before proceeding. Without the symptom, you'll waste turns querying everything; without the thread_id you can't anchor the trace.
When to apply
- User reports anything off about a chat thread (root, branched, or spawned).
- Bugs involving spawn cards, suggestion threads, document edits, Accept/Reject controls, plan-generation cards, or thread navigation.
- Any time a behaviour seems off and the user can hand you a thread_id.
Workflow
1. Connect to the local Postgres
The local Supabase DB is exposed on port 54322 with postgres/postgres credentials. Connection string:
PGPASSWORD=postgres psql -h 127.0.0.1 -p 54322 -U postgres -d postgres
If unsure, run pnpm exec supabase status from apps/web/ and read the URL line. If Supabase isn't running, ask the user to pnpm supabase:web:start — do not assume.
2. Walk the parent thread
Run a compact list first — full content can be large:
SELECT id, item_type, sequence_number, content_type,
LEFT(content, 80) AS preview, created_at
FROM thread_items
WHERE thread_id = '<thread_id>'
ORDER BY sequence_number;
Read the timeline. Look for:
- The user's prompt (item_type
message, firstcreated_bymatching the user). - Sub-status messages (
system) that show what flow ran (e.g. "Reviewing done briefs and adding notes"). - Any
tool_callitems in the parent itself (rare for spawn flows; common for in-context document edits). spawn_indicatoritems — these are the spawn cards. Always inspect their metadata, not just the preview.
3. Inspect spawn indicators in detail
SELECT id, sequence_number, jsonb_pretty(metadata)
FROM thread_items
WHERE thread_id = '<thread_id>'
AND item_type = 'spawn_indicator'
ORDER BY sequence_number;
Key metadata fields:
| Field | Meaning |
|---|---|
child_thread_id |
The spawned thread to follow next. |
target_thread_id |
The "main thread" of the target document/brief that the child branches from. |
origin_thread_id |
The thread where the user typed their request. |
spawn_type |
plan \ |
status |
pending \ |
document_id / brief_id |
The target document. |
bulk_operation_id |
Non-null only if spawned via the bulk tool. Multiple indicators sharing a key are one logical operation. |
dedupe_key |
sha256 of the (origin, target) pair for singleton suggestions and a per-batch hash for bulk. Both tools now populate this — DocumentSuggestionThreadService.spawnSuggestion() computes it when callers don't pass an explicit override, and DocumentCreationThreadService.spawnCreation() does the same for creation spawns. |
is_mirrored_reference |
true when this indicator is the duplicate posted in the target's main thread (so the brief's chat also shows the card). |
error_message |
Populated when status = 'failed'. |
If two indicators within the same parent thread reference the same (target_thread_id, instruction) pair within seconds, that's a duplicate spawn — see Pitfalls.
4. Walk each spawned child thread
For every interesting child_thread_id from step 3:
SELECT thread_id, item_type, sequence_number, content_type,
LEFT(content, 100) AS preview, created_at
FROM thread_items
WHERE thread_id = '<child_thread_id>'
ORDER BY sequence_number;
Then for each tool_call row (especially apply_diff / replace_document):
SELECT jsonb_pretty(metadata) FROM thread_items WHERE id = '<tool_call_item_id>';
Tool-call metadata fields you'll regularly read:
| Field | Meaning |
|---|---|
tool_call_id |
App-level ID (separate from row PK). |
tool_name |
apply_diff, replace_document, etc. |
status |
pending \ |
diffs[] |
Array of { search, replace } for apply_diff. |
timestamp |
When the call was emitted. |
updated_by |
The participant who last claimed/transitioned the call. |
prevents_ai_response |
If true, blocks the model from continuing until the call resolves. |
ai_generated |
True when the call came from the model. |
4b. Read flow-step reasoning (do not skip this)
item_type = 'system' rows in a child thread can be either plain status messages or flow-step rows — the latter carry the writer/specialist's full chain-of-thought, the partial output, AND the per-tool action results in metadata. This is the single highest-signal source for diagnosing sub-agent behaviour. Skipping it and reasoning only from final user-facing messages will mislead you, because writers regularly emit user-facing text that contradicts their own reasoning.
Identify flow-step rows by metadata.item_subtype = 'flow_step'. Quick survey across a child thread:
SELECT id, sequence_number, created_at,
metadata->>'agent_name' AS agent,
metadata->>'label' AS label,
metadata->>'output_status' AS output_status,
LEFT(metadata->>'output_text', 80) AS output_preview
FROM thread_items
WHERE thread_id = '<child_thread_id>'
AND item_type = 'system'
AND metadata->>'item_subtype' = 'flow_step'
ORDER BY sequence_number;
For any flow-step that looks suspicious, dump the rich fields. Postgres truncates wide jsonb output, so pipe through Python or jq:
PGPASSWORD=postgres psql -h 127.0.0.1 -p 54322 -U postgres -d postgres -tA \
-c "SELECT metadata FROM thread_items WHERE id = '<flow_step_id>';" \
| python3 -c "
import sys, json
m = json.loads(sys.stdin.read().strip())
print('label:', m.get('label'))
print('agent:', m.get('agent_name'))
print('output_status:', m.get('output_status'))
print('output_text:', (m.get('output_text') or '')[:1000])
print('reasoning_text:', m.get('reasoning_text') or '')
print('actions:')
for a in m.get('actions', []):
print(' ', a.get('tool_name'), '|', a.get('status'), '|', a.get('error_message'))
"
Flow-step metadata fields you'll always read:
| Field | Meaning |
|---|---|
agent_name |
Which specialist ran (e.g. Brief Writer, Blueprint Writer). Different agents have different prompts and capabilities. |
label |
The user-visible status (Adding TLDR to brief, Updating Engineering Principles blueprint). |
step_id |
handoff-<AgentName> — names the orchestration handoff that produced this step. |
flow_execution_id |
Correlates flow steps belonging to one execution; useful when several writers ran in parallel. |
reasoning_text |
The model's chain-of-thought — read this first when output looks wrong. It tells you what the model actually saw in its grounding prompt and why it chose what it chose. |
reasoning_status |
streaming \ |
output_text |
The post-reasoning text the agent emitted. Often contradicts reasoning_text (model fabrication after thinking). |
output_status |
streaming \ |
actions[] |
Per-tool results — see below. Required check for any "no tool_call was created" mystery. |
actions[] shape per entry: { tool_name, tool_call_id, status, started_at, completed_at, duration_ms, display_name, error_message?, output_position? }. Statuses: started, completed, failed.
Diagnostic recipes by symptom:
-
"The agent claims it edited the doc but no tool_call exists in this thread." Read
actions[]for the most recent flow-step. If you see{ status: 'failed', error_message: 'Stream ended before tool completed' }, the model started a tool call mid-stream and the connection dropped (apps/ai/src/common/aisdk/processors/action-tracker.ts:154-201writes this on cleanup). Theoutput_textmay STILL claim success — that's a model hallucination after the failure, not a real edit. -
"The agent keeps asking for clarification despite an unambiguous instruction." Read
reasoning_textof the latest flow-step. If it says things like "the document is described as ':warning: Brief is empty'" or "the writer mode is 'spawn-only suggestions'", the writer's grounding prompt was rendered without document content — meaningfetchDocumentContextreturned undefined. Trace: did the request carryevent.documentContext.documentId? For follow-up messages, this comes from the FE'smetadata.document_context. If a non-text-input path (e.g.submitQuestionAnswers) bypassed it, the prompt renders as empty. -
"The agent acted on the wrong instruction." Read
reasoning_textfor what the writer thought it was asked to do. If you see "The user has asked me to 'Process the current request'", the orchestrator handed off without populatingreasonorcontextand the writer received only the placeholder + references — seebuildHandoffMessageinapps/ai/src/modules/ai-agent/orchestration/agent.ts(search by name; line numbers shift). Confirm by checking that the seed/parent thread had a real instruction and that nothing else in the model's chain-of-thought references it. -
"
MaxTurnsExceededErrorwas logged but the user-visible result looks fine." Walk every flow-step'sactions[]. If a required tool call hasstatus: 'completed'somewhere in the run, the agent did its job and looped past —executeAgentTask's required-tool check should accept the partial run as success. If no required tool ever completed, the run genuinely failed. -
"User says the writer did the wrong thing on
local_editmode." Search the flow-step'sreasoning_textfor the phraseWriter mode:. The grounding prompt explicitly renders one of: -
:writing_hand:
Writer mode: local edit— capability islocal_edit, document content is loaded -
:shuffle:
Writer mode: spawn-only suggestions— capability isspawn_only, writer should callspawn_document_suggestion_threadnotapply_diffIf the mode rendered doesn't match what you expect, trace
core-agent-factory.service.ts:302-309's decision: capability islocal_editonly whenmodeContext.mode === 'brief' && fetchedDocumentContext(or the blueprint equivalents). IffetchedDocumentContextis falsy, capability collapses tospawn_only— same root cause as the empty-doc symptom above.
Why output_text and reasoning_text disagree:
Two separate fabrications happen in practice:
- The model's reasoning enumerates the actual document content it saw, then the user-facing output claims the document is empty. This is a known LLM trap with reasoning-mode models — the post-reasoning composition step doesn't always honour what the chain-of-thought concluded.
- The reasoning correctly identifies that an instruction is unambiguous (e.g. "place at the very beginning"), then the output asks the user the same clarifying question again. This is the model anchoring on the seed prompt rather than carrying forward the user's prior answers.
When output_text and reasoning_text contradict, trust reasoning_text for what the model actually saw, and treat output_text as the bug.
5. Check thread metadata + parent linkage
SELECT id, parent_thread_id, account_id, title, jsonb_pretty(metadata)
FROM threads
WHERE id IN ('<parent>', '<child>', '<target>');
Read metadata.created_via to know how the thread was bootstrapped:
created_via |
Meaning |
|---|---|
create_thread_for_account |
General account chat (no brief/document). |
create_thread_for_brief |
A brief's main thread — created by whoever opened the brief first, not necessarily the user. |
create_thread_for_document |
A document (blueprint/method) main thread. |
create_orchestration_child_thread |
Spawned child of a flow (suggestion, plan, etc.). |
If the user's request crosses thread types (e.g. they typed in their general account thread but the spawn lands on a brief's main thread), assume participant gaps are likely — check step 6 immediately.
6. Check participants
SELECT thread_id, participant_id, role, joined_at
FROM thread_participants
WHERE thread_id IN ('<parent>', '<child>', '<target>');
Participants matter because a long chain of UI behaviour gates on isParticipant:
- The parent thread (
origin_thread_id) usually has the user + AI agent. - The spawned child thread inherits parent participants via
create_orchestration_child_thread, plus thecreated_byuser via thekit.handle_new_thread_participanttrigger. - The target main thread (e.g. a brief's main thread the user has never opened) often has only the AI agent when the AI created it. If the user isn't on this thread, the brief workspace's
useScopedToolCallParticipantreturnsfalsefor them and the editor will silently skip the diff preview and Accept/Reject controls even though everything else looks correct. (This is the bug fixed in commit608de8fe1.)
7. Map findings to code
Once the data tells you what went wrong, locate where it happens. Common starting points:
| Concern | File |
|---|---|
| Spawn singleton tool | apps/ai/src/modules/ai-agent/tools/threads/spawn-document-suggestion.tool.ts |
| Bulk spawn tool | apps/ai/src/modules/ai-agent/tools/threads/bulk-document-suggestions.tool.ts |
| Spawn service (resolveTarget, createChild, postInitial, ensureParticipant) | apps/ai/src/modules/ai-agent/services/document-suggestion-thread.service.ts |
| Bulk orchestration service | apps/ai/src/modules/ai-agent/services/bulk-document-suggestions.service.ts |
| Conductor system prompt | apps/ai/src/modules/ai-agent/agents/conductor/conductor-orchestrator-prompt.ts |
| Thread chat container (loads overlay, viewedChildThread state) | packages/ai-chat/src/components/thread-chat.tsx |
| Thread chat inner (toolcall hooks, realtime items) | packages/ai-chat/src/components/thread-chat-main.tsx |
| Tool-call processor | packages/ai-chat/src/hooks/use-scoped-toolcall-processor.ts |
| Tool-call manager (extract → addToolCall → reactions) | packages/ai-chat/src/hooks/use-scoped-toolcall-manager.ts |
| Auto-preview pending diffs from initial items | packages/ai-chat/src/hooks/use-scoped-pending-diff-auto-preview.ts |
| Participant gate | packages/ai-chat/src/hooks/use-scoped-toolcall-participant.ts |
| Scoped store (per-thread isolated zustand) | packages/ai-chat/src/stores/thread-toolcall-context.tsx |
| Reactions (apply-diff, replace-document, navigation) | packages/ai-chat/src/stores/reactions/ |
| Pending review UI (Accept/Reject) | packages/ai-chat/src/components/scoped-changes-pending-review.tsx |
| Brief workspace layout (childThreadIdFromUrl wiring) | apps/web/app/home/[account]/briefs/_components/brief-workspace-layout.tsx |
| Blueprints workspace | apps/web/app/home/[account]/blueprints/_components/blueprints-shell.tsx |
| Spawn-card click → URL routing | packages/ai-chat/src/components/chat-thread-artifact-message.tsx + packages/ai-chat/src/lib/chat-thread-artifact-routing.ts |
| Thread RPCs (create_thread_for_brief, add_thread_participant, get_thread_details, create_orchestration_child_thread, triggers) | apps/web/supabase/schemas/23-chat-threads.sql |
| Toolcall DB helpers (setToolCallStatusIfCurrent) | packages/ai-chat/src/stores/db/toolcalls.ts |
Tip: when in doubt, gitnexus_context({name: "<symbol>"}) returns callers + callees + flows for any of the above symbols.
Pitfalls (catalogued from real bugs)
useThreadStore.currentThreadIdis alwaysnull. Nothing calls the store action that sets it. Any code branching onuseThreadStore.getState().currentThreadId !== toolCall.threadIdis effectively a no-op. Don't be fooled by it appearing to "do something."- Two
ThreadChatMaininstances render simultaneously when a child overlay is open. Each gets its ownThreadToolCallProvider(scoped store keyed by threadId). Both subscribe to the editor. When a tool_call belongs to one but not the other, only the matching scoped store should react. useScopedToolCallParticipantreads from the globaluseThreadStore.participants— i.e. the current page's main thread, not the scoped/overlay thread.** If the user isn't a participant of the page's main thread,isParticipantisfalsefor the overlay too, which silently killsaddToolCall's enqueue,markPendingChange, and the processor's run. (Origin of the missing-Accept-button bug.)- Brief main threads are often created by the AI agent, not the user. When
findCoreBriefThreadreturns a thread, it isn't auto-joining. Spawn flows must calladd_thread_participantfor the requesting user before creating the child thread, or the participant gate (#3) trips. - Singleton
spawn_document_suggestiontool does not populatededupe_key. Two calls within one turn for the same(target, instruction)create two child threads. Dedup is a TODO (seedocs/plans/spawn-suggestion-hardening.mdCommit 2). - The conductor can hallucinate failures after success. A
success: truefrom a spawn tool means "edit proposed; user will review", but a soft success message can lead the model to conclude it failed and retry. Cross-check the AI's user-facing text against the actual tool results. create_orchestration_child_threadcopies parent participants to the child — but the parent's participant set may be stale or AI-only. Don't assume the child has the user just because the user typed the prompt; verify with athread_participantsquery.- Spawn cards in the chat on the
/briefs/<id>chat tab were historically dropped from the URL. Pre-fix,effectiveChildThreadIdwas forced tonulloutside plan/task tabs, and?threadId=…navigation was a no-op. If the user reports "I clicked the card but the spawned thread didn't open," checkbrief-workspace-layout.tsxfirst. add_thread_participantis idempotent and auto-propagates to the parent thread when the child has aparent_thread_id. Use it as the universal seat operation; don't write tothread_participantsdirectly.spawn_indicatoritems are mirrored. Whenorigin_thread_id !== target_thread_id, the indicator is posted in both threads, withis_mirrored_reference: trueon the origin's copy. Don't double-count duplicates by accident.- A spawn_indicator marked
completeddoes NOT mean the writer produced a usable suggestion. Pre-fix, every BullMQ-completed agent run flipped the indicator tocompletedeven if the child thread had zerotool_callrows (stream cut off mid-call, writer routed torequest_clarification, etc.). After commit951a04fcc,finalizeChildOutcomechecks for usable tool_calls and downgrades tofailed; if you see a stale "Suggestion Ready" card without a tool_call, you're looking at pre-fix data or a regression. buildHandoffMessagefalls back to"Process the current request"when bothreasonandcontextare missing on the handoff (apps/ai/src/modules/ai-agent/orchestration/agent.ts:1735). Symptom in the writer'sreasoning_text: it says it received "Process the current request" with only references and no actual instruction. Post-fix (1390305f3), the originating user message is carried forward as a final fallback.submitQuestionAnswersoriginally didn't passdocument_context. Question-answer submissions in a child thread overlay reached the chat-processing consumer withevent.documentContext = undefined→fetchDocumentContext(undefined, …)returned no content → writer's prompt rendered :warning:Brief is emptyandbriefWriterCapability = 'spawn_only'. Fixed in8295e2ebd. If you see those two markers together in a follow-up flow-stepreasoning_text, the request body lacked document_context — check that the FE caller is passing it.- The writer's
output_textandreasoning_textcan disagree. The reasoning often correctly enumerates document content the model saw, while the output fabricates "empty" or asks already-answered clarification questions. Always trustreasoning_textwhen diagnosing what the model actually saw.
Useful query recipes
Tool-call status sweep across both parent and children
SELECT thread_id, id, item_type,
metadata->>'tool_name' AS tool_name,
metadata->>'status' AS status,
metadata->>'tool_call_id' AS tool_call_id,
created_at
FROM thread_items
WHERE thread_id IN ('<parent>', '<child1>', '<child2>')
AND item_type = 'tool_call'
ORDER BY thread_id, sequence_number;
All children of a parent thread
SELECT id, title, status, metadata->>'created_via' AS created_via, created_at
FROM threads
WHERE parent_thread_id = '<parent>'
ORDER BY created_at;
Spawn-indicator audit (find duplicates within a parent)
SELECT
metadata->>'target_thread_id' AS target,
metadata->>'spawn_type' AS spawn_type,
COUNT(*) AS spawn_count,
array_agg(metadata->>'child_thread_id') AS child_ids,
array_agg(created_at ORDER BY created_at) AS times
FROM thread_items
WHERE thread_id = '<parent>'
AND item_type = 'spawn_indicator'
GROUP BY 1, 2
HAVING COUNT(*) > 1;
Flow-step audit (find writer failures and stream cutoffs across a child thread)
PGPASSWORD=postgres psql -h 127.0.0.1 -p 54322 -U postgres -d postgres -tA \
-c "SELECT metadata FROM thread_items
WHERE thread_id = '<child_thread_id>'
AND item_type = 'system'
AND metadata->>'item_subtype' = 'flow_step'
ORDER BY created_at;" \
| python3 -c "
import sys, json
for i, line in enumerate(sys.stdin):
line = line.strip()
if not line: continue
m = json.loads(line)
print(f'--- step {i+1}: {m.get(\"label\")} ({m.get(\"agent_name\")}) ---')
print(' output_status:', m.get('output_status'))
out = (m.get('output_text') or '').replace('\n', ' ')[:200]
print(' output:', out)
failed = [a for a in m.get('actions', []) if a.get('status') == 'failed']
for a in failed:
print(' FAILED ACTION:', a.get('tool_name'), '|', a.get('error_message'))
rt = (m.get('reasoning_text') or '')
if 'empty' in rt.lower() or 'spawn-only' in rt.lower():
print(' ⚠️ reasoning suggests empty doc / spawn-only mode')
"
This is the fastest way to find the failure mode for a misbehaving spawn child: prints each step's label, agent, output status, any failed tool actions with their error messages, and flags reasoning that mentions "empty" or "spawn-only" (the two canonical grounding-prompt markers when document context didn't load).
Diff content of a pending tool_call
SELECT jsonb_pretty(metadata->'diffs')
FROM thread_items
WHERE id = '<tool_call_item_id>';
Check whether a user is on the relevant threads
SELECT t.id AS thread_id, t.title, t.metadata->>'created_via' AS created_via,
(tp.participant_id IS NOT NULL) AS user_is_participant,
tp.role
FROM threads t
LEFT JOIN thread_participants tp
ON tp.thread_id = t.id AND tp.participant_id = '<user_uuid>'
WHERE t.id IN ('<parent>', '<child>', '<target>');
Output: what to give the user
After the trace, deliver:
- A timeline table of the parent thread (sequence, type, summary, time) so they can see what happened in plain language.
- A "what each spawn produced" section for any non-trivial spawn — the child thread items in order and any pending tool_calls' diffs.
- A grounded root-cause statement. Cite specific rows ("
thread_participantsfor1de78d90-…only contains the AI agent — the user isn't a participant of the brief's main thread, which killsuseScopedToolCallParticipantfor the overlay") rather than vague theories. - A fix recommendation with file paths and line-level specificity. If multiple fixes are viable, list them with tradeoffs and pick one.
- A retest path — what the user can do to verify the fix without re-spawning, when applicable. If existing rows must be patched to reproduce the green path, name the SQL or service call needed.
Anti-patterns
- Don't speculate without querying. Symptoms can be misleading; the DB is ground truth.
- Don't try to verify in the browser before reading the data. UI behaviour layers many gates; the DB tells you which gate tripped fastest.
- Don't restart the dev server or supabase. Diagnostic work is read-only against existing state.
- Don't write to
thread_participantsdirectly to "patch" a missing seat. Useadd_thread_participant(RPC) — it has the auth and propagation logic. - Don't propose fixes that paper over
useScopedToolCallParticipant. If the user's missing from a thread they should be on, fix the seating, not the hook. - Don't conclude a
tool_call_idfailed just because the AI's user-facing message says so. Cross-checkmetadata.statusand the tool's actual return value.
04 同仓库更多 Skills
writing-waterfall-requirements-documents
Write a waterfall requirements document: elicit, structure and review testable, traceable requirements, then baseline the specification before design.
writing-vision-and-values-statements
Write a V2MOM vision a reader can test and a ranked list of values that settles real tradeoffs, so the rest of the document has a clear anchor.
writing-system-prompts-for-claude
Write Claude prompts and CLAUDE.md files that supply exact inputs, scope the task, and define done so the first attempt can be checked.
writing-page-specific-website-copy
Website copywriting by page type: write homepage, landing page, pricing page and feature page copy that fits each page's visitor and single job.
writing-internal-press-releases
How to write an internal press release: the one-page working backwards press release that opens a PR/FAQ document before anything is built.
writing-email-sequences-that-sell
Email sequence copywriting for nurture and sales: give each email one job, write clear subject lines, and close with one specific call to action.