# Workflow: Improve Workflow

Refine workflow documents based on friction encountered during use.

## Who should do this work

- **Main/Haiku**: Gather friction data
- **Opus subagent**: Prioritize improvements
- **Varies by complexity**: Apply improvements
- **Main**: Verify and reflect

## When to use

- After using workflow and encountering friction
- Instructions need refinement
- Add missing steps or improve ownership
- Periodic maintenance

## Inputs required

- **workflow_path** - Path to workflow file
- **friction_notes** (optional) - Specific friction points

## Task document

Create: `.claude/plugin-data/workflow-architect/tasks/improve-workflow-<workflow-name>-<date>.md`

## Output

- Task doc records changes
- Improved workflow verified and ready
- Optional follow-up audit offered

---

## Subtasks

### 1. Gather friction data

Subagent: Main or haiku.

**Do:**
- Check `.claude/plugin-data/workflow-architect/tasks/` for mentions
- Ask user for pain points
- List in task doc

**Focus areas:**
- Step clarity (unclear what to do)
- Missing steps
- Ownership ambiguity (who does what)
- Missing required reads
- Inadequate verification

---

### 2. Prioritize improvements

Subagent: opus.

**Do:**
- Review friction notes
- Filter one-time issues
- Prioritize by frequency/impact
- Write to task doc

**Priority:**
- **High:** Missing critical steps, ambiguous ownership, missing verification
- **Medium:** Unclear instructions, missing context reads
- **Low:** Style, wording

---

### 3. Apply improvements

Subagent: Varies by complexity.
Read: `${CLAUDE_PLUGIN_ROOT}/references/layout/workflow-structure.md`

**Do per improvement:**
- Read workflow file
- Make targeted edit
- Document in task doc

**Common improvements:**
- Add missing steps
- Clarify ownership (main vs subagent)
- Add missing "Must read" refs
- Add verification steps
- Improve step descriptions

---

### 4. Verify and reflect

Subagent: Main.

**Do:**
- Spot-check modified file
- Verify subtasks have clear ownership
- Verify required sections present
- Report summary

Offer: "Run quick audit on improved workflow?"

---

### 5. Record decisions (if applicable)

Subagent: Main.

**When to record:**
- Non-standard structures
- Delegation pattern changes
- Exceptions to best practices

**How:**
- Template: `references/tool-patterns/templates/decision-record-template.md`
- Write: `<plugin_path>/.decisions/YYYY-MM-DD-<topic>.md`