cc-os/plugins/cc-architect/workflows/improve-plugin-docs.md

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.