# 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