Tendril Debug Job

tendril-debug-job

Analyze a job's execution artifacts to identify issues and improvement opportunities in Tendril, the promptware instructions, memory, or tools.

Invocation

/tendril-debug-job <job-id> <comment>

• job-id - Five-digit job id (e.g., 00458). A full path to a job log also works.
• comment - Free-text describing what to look for or what went wrong

Job Artifacts

Every job writes four files, flat, into $TENDRIL_HOME/Jobs/. They share one stem:

{jobId}-{planId}-{promptware}      e.g. 00458-00044-ExecutePlan
{jobId}-{promptware}               when the job has no plan (e.g. CreatePlan)

Locate them with a glob on the job id:

ls "$TENDRIL_HOME/Jobs/00458-"*

The promptware type is the last dash-separated segment of the stem; the plan id, when present, is the middle segment. There is no Logs/ folder anywhere - not under promptwares, not under plans.

What This Skill Does

1. Reads the Job Log, the Job Prompt, and the Job Raw Log
2. Reconstructs the agent's execution timeline: tool calls, decisions, errors, retries
3. Cross-references with the promptware's Program.md, Memory, and Tools
4. Identifies concrete improvements to Tendril code, promptware instructions, or agent behavior
5. Produces actionable recommendations

Execution Steps

Phase 1 - Read the Job Log and Job Prompt

The Job Log ({stem}.md, produced by JobLogWriter) has this structure:

# Job Log {stem}

- **JobId:** {id}
- **PlanId:** {planId}   # present whenever the job produced or targeted a plan
- **Status:** {Completed|Failed|Timeout}
- **Exit Code:** {0|1|N/A}
- **Started:** {timestamp}
- **Completed:** {timestamp}
- **Duration:** {seconds}s
- **Provider:** {claude|copilot|codex|...}
- **SessionId:** {id}
- **Cost:** ${amount}
- **Tokens:** {count}

## CLI Command
{full command line}

## Final Output
{agent's last text response}

## Outcome
{commits, verifications, final plan state - ExecutePlan/RetryPlan only}

## Agent Log - {action} ({timestamp})
{narrative the agent appended mid-run via `tendril job add-log`}

The compiled prompt is not in this file. Read {stem}.prompt.md for the full firmware + Program.md + references + custom instructions.

Extract:

• The promptware type and plan id (from the stem)
• The program folder: $TENDRIL_HOME/Promptwares/{promptware} (in a dev checkout, src/Ivy.Tendril/Promptwares/{promptware})
• Status, exit code, duration, cost, tokens
• The agent's own narrative from the ## Agent Log sections
• The final output

Phase 2 - Analyze the Raw JSONL

{stem}.raw.jsonl is the CLI's --output-format stream-json output. Each line is a JSON object with a type field:

{stem}.eventwire.jsonl is Tendril's own parsed view of that same stream - use it when you want Tendril's interpretation (including PermissionDenialEvent) rather than the provider's raw wire format.

Analysis approach (use targeted reads, never read the whole file if large):

1. Count total lines: wc -l
2. Extract tool call patterns:
   • Grep for "tool_use" to find all tool calls
   • Count each tool type (Read, Write, Edit, Bash, Grep, Glob)
   • Identify repeated reads of the same file (redundant work)
   • Find failed tool calls (look for "error" or "is_error":true in tool_result lines)
3. Token usage:
   • Sum input_tokens, output_tokens from assistant messages
   • Check cache_read_input_tokens vs cache_creation_input_tokens for cache efficiency
4. Error patterns:
   • Grep for error, failed, exception in tool results
   • Count build-fix-build cycles (consecutive Bash calls with compilation errors)
   • Identify thrashing (read-edit-read-edit on same file)
   • src/scripts/AnalyzeFailed.ps1 dumps every failed shell command across all raw logs
5. Timeline:
   • First and last timestamps for wall-clock duration
   • Long gaps between messages (rate limiting, slow tools)

Phase 3 - Cross-Reference with Promptware Source

Read the promptware's source files from the program folder:

Check:

• Did the agent follow Program.md instructions in order?
• Did it skip steps or go off-script?
• Are there Memory entries that should have prevented a mistake?
• Are there Tools that should have been used but weren't?
• Did the compiled prompt provide sufficient context?

Phase 4 - Cross-Reference with Tendril Source

Based on findings, check relevant Tendril source files:

Phase 5 - Produce Recommendations

Output a structured analysis directly in the conversation (do NOT write files):

## Execution Summary

- **Job:** {jobId} ({promptware}, plan {planId})
- **Status:** {status} (exit code {code})
- **Duration:** {duration}
- **Tokens:** {input + output} (cache hit: {ratio}%)
- **Tool Calls:** {count} ({breakdown by type})
- **Errors:** {count}

## Timeline

Brief narrative of what the agent did step by step.

## Findings

### {Finding Title}

- **Category:** {Instruction Gap | Memory Gap | Tool Gap | Tendril Bug | Token Waste | Error Loop | Permission Issue}
- **Severity:** {Low | Medium | High | Critical}
- **Evidence:** {specific tool calls, line numbers in JSONL, quotes from output}

{Description of the issue.}

**Root Cause:** {why this happened}
**Recommendation:** {concrete fix - which file, what to change}

---

{Repeat for each finding}

## Concrete Fixes (Priority Order)

1. **[Severity] {file path}**: {what to change and why}
2. ...

Rules

• Read-only: Do NOT modify source code, promptware instructions, or memory files. Output recommendations only.
• Always produce findings, even if the execution was clean - "executed as expected" is a valid finding.
• Be specific: Cite JSONL line ranges, tool call sequences, and exact prompt sections.
• The user's comment is your guide: Prioritize investigating what they flagged.
• Use targeted reads: JSONL files can be huge. Use grep, offset/limit, and line counts rather than reading entire files.
• Focus on actionable items: Every finding should have a concrete recommendation pointing to a specific file.
• Distinguish agent mistakes from system issues: An agent going off-script is a Program.md problem; a tool failing is a Tendril infrastructure problem.