# Workflow: Improve Plugin Docs

Harvest friction notes and apply targeted improvements to plugin documentation.

## Who should do this work

| Phase | Model | Why |
|-------|-------|-----|
| Research | Haiku | File gathering, friction collection |
| Processing | Sonnet | Prioritization, patch drafting |
| Review | Opus | Quality decisions, structure verification |
| Apply + Cleanup | Haiku | Mechanical edits, file operations |

## When to use

- After several tasks, harvesting learnings
- Recurring friction in knowledge docs
- Periodic maintenance

## Inputs required

- **target_skill** - Path to skill directory
- **task_scope** - Task documents to scan (default: all `.claude/plugin-data/plugin-architect/tasks/`)

## Task document

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

---

## Phase 1: Research (Haiku)

**Artifact:** Task doc with collected friction notes

**Do:**
- Read task docs in scope
- Extract `## Friction / Improvement Notes` sections
- Group by target file
- Read current state of affected docs
- Write to task doc:
  - `## Collected Friction Notes` (grouped by file)
  - `## Current Doc State` (file paths and line counts)

**Exit:** If no friction notes found, report and end workflow.

---

## Phase 2: Processing (Sonnet)

**Read:** Task doc (friction notes, doc state)

**Artifact:** Task doc with prioritized improvements and proposed patches

**Do:**
- Filter noise (one-offs, already fixed)
- Identify patterns (repeated = high priority)
- Rank by impact
- For each high-priority improvement:
  - Read target file and parent `reference.md`
  - Draft patch (add/change/remove)
  - Keep small and focused
  - If doc would exceed ~150 lines: propose split
- Write to task doc:
  - `## Prioritized Improvements` (ranked list with reasoning)
  - `## Proposed Patches` (per file, with before/after context)

**Checkpoint:** Confirm prioritization and patches with user before proceeding.

---

## Phase 3: Synthesis (Opus + Haiku cleanup)

**Read:** Task doc (prioritized improvements, proposed patches)

**Artifact:** Updated docs + final report in task doc

**Do (Opus review):**
- Verify no structure breakage
- Verify patches address friction
- Flag if needs user decision
- Mark: approved/rejected/needs-revision

**Do (Haiku apply + cleanup):**
- Apply approved patches
- If splitting doc: update parent `reference.md`
- Write to task doc:
  - `## Applied Changes` (files changed, patch status)
  - `## Summary` (rejected patches and why, verification suggestions)

**Exit:** Report files changed and suggest re-running affected workflows to verify.