91 lines
2.6 KiB
Markdown
91 lines
2.6 KiB
Markdown
|
# 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.
|