59 lines
1.6 KiB
Markdown
59 lines
1.6 KiB
Markdown
|
# Patch Workflow
|
||
|
|
|
||
|
|
How to propose and apply improvements to knowledge docs.
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
The improve-docs workflow harvests friction notes from task documents, prioritizes them, and applies targeted patches. This file describes the mechanics.
|
||
|
|
|
||
|
|
## Patch format
|
||
|
|
|
||
|
|
A patch is a proposed change to a specific file:
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
### Patch: references/layout/plugin-structure.md
|
||
|
|
|
||
|
|
**Source:** task doc `new-plugin-foo-2024-01-15.md`
|
||
|
|
|
||
|
|
**Change type:** Addition
|
||
|
|
|
||
|
|
**Location:** After "## plugin.json format" section
|
||
|
|
|
||
|
|
**Content to add:**
|
||
|
|
> **Path requirements:** All paths in plugin.json must be relative and start with `./`
|
||
|
|
|
||
|
|
**Rationale:** Multiple tasks hit friction because this wasn't documented.
|
||
|
|
```
|
||
|
|
|
||
|
|
## Change types
|
||
|
|
|
||
|
|
- **Addition**: Add new content (most common)
|
||
|
|
- **Clarification**: Reword existing content for clarity
|
||
|
|
- **Correction**: Fix incorrect information
|
||
|
|
- **Restructure**: Move content or split files
|
||
|
|
- **Removal**: Delete outdated or wrong content (rare)
|
||
|
|
|
||
|
|
## Patch size guidelines
|
||
|
|
|
||
|
|
- Keep patches small and focused
|
||
|
|
- One friction point = one patch
|
||
|
|
- If a patch would make a file exceed 150 lines, propose a split instead
|
||
|
|
|
||
|
|
## Approval levels
|
||
|
|
|
||
|
|
Not all patches need the same scrutiny:
|
||
|
|
|
||
|
|
| Change type | Approval |
|
||
|
|
|-------------|----------|
|
||
|
|
| Addition (small) | Auto-apply OK |
|
||
|
|
| Clarification | Auto-apply OK |
|
||
|
|
| Correction | Review recommended |
|
||
|
|
| Restructure | User approval required |
|
||
|
|
| Removal | User approval required |
|
||
|
|
|
||
|
|
## After applying patches
|
||
|
|
|
||
|
|
1. Update any parent reference.md if file structure changed
|
||
|
|
2. Note applied patches in the task document
|
||
|
|
3. Consider re-running a workflow that hit this friction to verify improvement
|