/tendril-debug-plan

name: tendril-debug-plan
description: Debug a Tendril plan by analyzing its execution logs, session JSONL, verification results, and checking infrastructure. Produces actionable bugfix and improvement recommendations. Use when the user wants to investigate why a plan failed, behaved unexpectedly, or to audit plan execution quality.

tendril-debug-plan

Debug and analyze Tendril plan executions end-to-end — from plan creation through checking/verification — and produce a set of concrete bugfix and improvement recommendations.

Invocation

/tendril-debug-plan <planid> <note>

• **planid** — 5-digit Tendril plan ID (e.g., `03451`)
• **note** — free-text context about what to look for (e.g., "verification passed but shouldn't have", "took forever", "got stuck in Building state")

What This Skill Does

1. Gathers all artifacts for a plan: `plan.yaml`, revisions, logs, costs, verification reports, session JSONL 2. Analyzes the execution timeline, token usage, tool call patterns, and error loops 3. Cross-references findings with Tendril source code and promptware instructions 4. Produces a structured recommendations report with concrete fixes

Execution Steps

Phase 1 — Gather Plan Artifacts

Resolve paths from environment:

• `TENDRIL_HOME` — base config/data directory
• `TENDRIL_PLANS` — plans directory (defaults to `$TENDRIL_HOME/Plans`)
• `REPOS_HOME` — for locating Tendril source code

Read these files from the plan folder (`$TENDRIL_PLANS/{planid}-*/`):

| File | Purpose | | ------------------- | ---------------------------------------------------------------------------------------------------------- | | `plan.yaml` | Plan metadata: state, repos, commits, PRs, verifications, dependsOn | | `revisions/*.md` | Plan scope, acceptance criteria, verification checkboxes. Last one is the one that is the executable one. | | `costs.csv` | Token/cost breakdown per promptware (if available) | | `verification/*.md` | Verification reports (PreExecution, IvyFrameworkVerification, etc.) | | `worktrees/` | Check if worktrees were created/cleaned up |

The plan folder holds **no logs**. Every job that ran against the plan wrote its artifacts flat into `$TENDRIL_HOME/Jobs/`, named `{jobId}-{planId}-{promptware}`. Find them all for a plan with:

ls "$TENDRIL_HOME/Jobs/"*"-{planid}-"*

| File | Purpose | |------|---------| | `{stem}.md` | Job Log — status, timings, cost, CLI command, final output, agent `## Agent Log` narrative | | `{stem}.prompt.md` | Job Prompt — the exact prompt handed to the agent | | `{stem}.raw.jsonl` | Job Raw Log — full unparsed CLI session data | | `{stem}.eventwire.jsonl` | Job Eventwire Log — Tendril's parsed event stream |

Note that the `CreatePlan` job that created the plan is named `{jobId}-CreatePlan` with **no** plan id, so it will not appear in the glob above. Use `/tendril-debug-job` to drill into any single job.

Phase 2 — Locate and Analyze Session JSONL

Each Job Log contains a `SessionId`. The raw Claude session data lives at:

~/.claude/projects/*/{SessionId}.jsonl

Use `find ~/.claude/projects -name "{SessionId}.jsonl"` to locate each file.

For each JSONL session, extract:

**Token Usage:**

• Sum `input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens` from `type: "assistant"` messages
• Cache hit ratio: `cache_read / (cache_read + cache_creation + input)`
• Flag messages with unusually high `input_tokens` (context bloat)

**Tool Call Patterns:**

• Count each tool type (Read, Write, Edit, Bash, Grep, Glob)
• Identify repeated reads of the same file (redundant)
• Identify failed tool calls and their errors
• Detect thrashing: read-edit-read-edit cycles on the same file

**Error Patterns:**

• Grep for `error`, `failed`, `exception`, `timeout` in tool results
• Count compilation fix-retry cycles (build → error → edit → build loops)
• Permission errors, missing files, environmental issues

**Time Analysis:**

• Wall-clock duration from first to last timestamp
• Long gaps between messages (slow tools, rate limiting)
• Timeout detection

Use the `Analyze-SessionJsonl.ps1` tool if available at:

$REPOS_HOME/Ivy-Tendril/src/Ivy.Tendril.TeamIvyConfig/Promptwares/PlanEvaluator/Tools/Analyze-SessionJsonl.ps1

Phase 3 — Analyze the Checking/Verification Pipeline

This is the core debugging focus. Examine:

**Pre-execution checks (ExecutePlan Step 1.5–1.8):**

• Did dependency checking work correctly? (`dependsOn` plans completed, PRs merged)
• Did worktree validation catch problems? Or miss them?
• Did code state validation (`**Current implementation**` blocks) match reality?
• Did auto-commit handle dirty files properly?

**Verification execution (ExecutePlan Step 7):**

• Which verifications ran vs were skipped?
• Did verifications match what the plan revision checkboxes specified?
• For each verification: did the prompt execute correctly? Were failures diagnosed?
• How many fix-retry cycles occurred (max 3 allowed)?
• Were verification results written to `verification/` correctly?
• Were plan verification statuses updated via `tendril plan set-verification`?

**Post-verification (ExecutePlan Step 7.5–8):**

• Were recommendations generated?
• Was the worktree left clean?
• Were zombie processes detected/killed?

**CheckResult / completion verification (JobService):**

• For CreatePlan: did `VerifyCreatePlanResult` find the plan folder or trash entry?
• Did `CheckDependencies` correctly evaluate dependency plan states?
• Did `TryBlockForDependencies` transition appropriately?

Cross-reference each finding with:

• `Promptwares/{Type}/Program.