Skip to content

Commit 50ef776

Browse files
mattthomps1claude
mattthomps1
and
claude
committed
docs: add solution doc for research workflow first-use failure
Documents the root cause, fix, and prevention checklist for the workflow-skill input mismatch that caused /workflows:research process to stall on first use with empty directories. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 1f78062 commit 50ef776

1 file changed

Lines changed: 128 additions & 0 deletions

File tree

‎docs/solutions/integration-issues/workflow-skill-transcript-input-mismatch.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: "/workflows:research process stalls on inline transcript with empty plans directory"
3+
date: 2026-02-13
4+
category: integration-issues
5+
tags: [workflow-automation, research-workflow, transcript-processing, state-handling, first-use-failure]
6+
severity: high
7+
component: plugins/compound-engineering/commands/workflows/research.md + plugins/compound-engineering/skills/transcript-insights/SKILL.md
8+
resolution_time: 30 minutes
9+
---
10+
11+
# /workflows:research process stalls on inline transcript with empty plans directory
12+
13+
## Problem
14+
15+
`/workflows:research process this transcript [content]` stalls when used as the first research action. Claude creates directories but never produces output. Brainstorm and plan workflows are unaffected.
16+
17+
**Symptom:** The model appears stuck after creating `docs/research/` directories. No transcript is saved, no interview snapshot is generated.
18+
19+
**Trigger:** Empty research directories (no prior transcripts, plans, or interviews).
20+
21+
## Root Cause
22+
23+
Two cascading bugs at the integration boundary between the workflow command and its downstream skill:
24+
25+
**Bug 1: Workflow command doesn't pass inline content to the skill.**
26+
Phase 2 of `research.md` only checks for `.md` files in `docs/research/transcripts/`. When the directory is empty, it reports "no transcripts found" and exits. The `transcript-insights` skill supports inline content (Step 1: "If content is pasted directly, proceed"), but the workflow command never provides a path for inline content to reach the skill.
27+
28+
**Bug 2: Skill stalls on empty plans directory.**
29+
Even if Bug 1 were fixed, `transcript-insights` Step 2 tries to list research plans from `docs/research/plans/` with no empty-state fallback. On first use, the directory is empty and the model stalls trying to reconcile the instruction to "list plans" with nothing to list.
30+
31+
**Pattern:** This is a "first-use failure" — everything works once artifacts exist from prior runs, but the first invocation with empty directories fails.
32+
33+
## Solution
34+
35+
### Fix 1: research.md — Add inline content handling
36+
37+
Added a "Check for Inline Content" section before "Check for Transcripts" in Phase 2:
38+
39+
```markdown
40+
### Check for Inline Content
41+
42+
If the research phase argument contains more than just the word "process"
43+
(i.e., transcript content was provided inline):
44+
45+
1. Extract the transcript content from the argument (everything after "process")
46+
2. Look for a meeting title or date in the content to generate a filename.
47+
Use the format: YYYY-MM-DD_<meeting-title-slug>_transcript.md
48+
3. Save the content to docs/research/transcripts/[filename]
49+
4. Skip the transcript selection step — proceed directly to Process Selected Transcript
50+
```
51+
52+
Updated "Check for Transcripts" with a guard: "If inline content was already saved above, skip this section." Also updated the error message to mention the inline option.
53+
54+
### Fix 2: transcript-insights/SKILL.md — Add empty-state handling
55+
56+
Replaced the unconditional plan listing in Step 2 with:
57+
58+
```markdown
59+
Check for files in docs/research/plans/.
60+
61+
**If no plans exist:**
62+
Set research_plan: ad-hoc in frontmatter and proceed to Step 3.
63+
64+
**If plans exist:**
65+
List existing research plans...
66+
[existing flow unchanged]
67+
```
68+
69+
Removed the AskUserQuestion confirmation for empty state — the user already committed to processing by providing a transcript. Just default to ad-hoc silently.
70+
71+
## Why It Works
72+
73+
- **Inline content becomes first-class:** The workflow now extracts, saves, and passes inline content through to the skill, matching what the skill already documented as supported input.
74+
- **Empty state is a non-event:** When no plans exist, the skill defaults to ad-hoc without blocking. The user can create plans later.
75+
- **Backward compatible:** The existing file-based flow is untouched. The inline path only activates when the argument contains more than "process".
76+
- **Converges at the same point:** Both the inline and file-based paths meet at "Process Selected Transcript" with a file path, so all downstream logic is shared.
77+
78+
## Why Other Workflows Were Unaffected
79+
80+
| Workflow | Why it works |
81+
|----------|-------------|
82+
| `/workflows:brainstorm` | Accepts inline descriptions directly — no file dependency |
83+
| `/workflows:plan` | Has explicit fallback: "If no brainstorm found, run idea refinement" |
84+
| `/workflows:research` (phase menu) | Just counts files — 0 is valid |
85+
| `/workflows:research plan` | Creates from scratch — no dependency on existing artifacts |
86+
| `/workflows:research personas` | Explicitly handles empty state: "No processed interviews found" |
87+
88+
## Prevention: First-Use Failure Checklist
89+
90+
This class of bug happens when workflow commands and skills have mismatched input handling or missing empty-state fallbacks. When writing new workflow commands or skills, check:
91+
92+
### Input Contract
93+
- [ ] Every supported input format (file path, inline content, empty) is documented in both the workflow command AND the skill
94+
- [ ] If a skill says it accepts inline content, the workflow command has a path to pass it through
95+
- [ ] Empty input is handled explicitly (not silently ignored)
96+
97+
### Empty-State Handling
98+
- [ ] Every instruction that reads from a directory has an "If empty" branch
99+
- [ ] Empty-state messages guide the user to a next action (not just "not found")
100+
- [ ] Default behavior exists for first-use (e.g., ad-hoc tagging, skip to next step)
101+
102+
### First-Run Test
103+
- [ ] Can a user run this workflow with NO prior artifacts and succeed?
104+
- [ ] All directories are created upfront (mkdir -p in Directory Setup)
105+
- [ ] File selection handles 0, 1, and N files explicitly
106+
107+
### Integration Boundary
108+
- [ ] Workflow command documents what it passes to the skill
109+
- [ ] Skill documents what it expects to receive
110+
- [ ] Return contract is documented (what file gets created, what frontmatter fields)
111+
112+
**Core insight:** Design workflows for the worst case (empty, first-run) first, then optimize for the common case (existing artifacts).
113+
114+
## Files Changed
115+
116+
| File | Change |
117+
|------|--------|
118+
| `plugins/compound-engineering/commands/workflows/research.md` | Added inline content handling before file check |
119+
| `plugins/compound-engineering/skills/transcript-insights/SKILL.md` | Added empty-state handling for plans directory |
120+
| `plugins/compound-engineering/.claude-plugin/plugin.json` | Version 2.32.0 → 2.32.1 |
121+
| `plugins/compound-engineering/CHANGELOG.md` | Added Fixed section for 2.32.1 |
122+
123+
## References
124+
125+
- Issue: [EveryInc/compound-engineering-plugin#187](https://github.com/EveryInc/compound-engineering-plugin/issues/187)
126+
- Fix plan: `docs/plans/2026-02-13-fix-research-process-first-action-plan.md`
127+
- Original feature plan: `docs/plans/2026-02-11-feat-user-research-workflow-plan.md`
128+
- Plugin versioning guide: `docs/solutions/plugin-versioning-requirements.md`

0 commit comments

Comments
 (0)