# Documentation optimization

Use for `/picm-optimize` or accepted maintenance-integrated optimization under the [shared contract](../SKILL.md). Improve navigation, clarity, and upkeep while preserving unique constraints and intended outcomes. This isn't a semantic-equivalence proof or a promise of token savings.

## Scope

Discover eligible agent-facing instructions, maps, contracts, skills/prompts, routed references/recipes/handoffs/roles/stages/rules/examples/identity, and relevant pointed-to documents. Names are signals, not a schema. Follow relevant pointers within agreed scope, not every link; ask about an unclassifiable custom area. Read deliberately; revisit only for freshness, incomplete evidence, or uncertain operation results.

Edit documentation only. Keep source code, tests, manifests, build/runtime paths, executable scripts, `.picm/` policy/config/reports, generated docs, per-run artifacts, and unrelated material unchanged. Respect the shared pre-read privacy boundary and generated/do-not-edit exclusions. Build no crawler, optimizer/equivalence engine, orchestration layer, or custom TUI.

During maintenance, retain its report and reuse answered intake; the scope, ledger, audit, and sign-off requirements below still apply.

## Preservation ledger and redundancy

For each inspected document, record unique constraints: privacy/safety, permissions/prohibitions, approval/review, commands/checks, behavior/routing, outputs/handoffs/uncertainty, domain facts/quality/terminology/exceptions, and authoritative/generated boundaries.

Preserve each in place or at a clearly reachable authoritative home. Intentional repetition, transition cases, fixtures, and compatibility shims are also constraints; retain them or ask for a preservation mechanism. The ledger aids review, not proof of equivalence.

Then load and apply [redundancy review](redundancy-review.md) within and across the discovered set before opportunities or a no-op conclusion. Include dispositions and coverage limits in the audit; compare authoritative-home claims across every inspected document. Contradictions or repeated claims without a supported canonical home need an opportunity or user decision.

## Writing-lens audit and opportunities

Begin the first discovery response with `### Writing-lens audit` and these five ordered rows, before opportunities, direction, or no-op:

| Row | Examine |
| --- | --- |
| **Context pointers** | Target plus distinct read conditions; always-needed prerequisites remain reachable. |
| **Information hierarchy** | Shared constraints near execution; conditional reference disclosed; definitions/rules/caveats co-located. |
| **Canonical home** | Equivalent guidance at one supported reachable home; conflicts need a decision. |
| **Completion criteria** | Recognizable existing results, without invented requirements/gates. |
| **Pruning** | True duplication, stale cheap-lookup caches, and behavioral no-ops; retain intentional safety/review/local repetition. |

For each row use **Pass**, **Opportunity**, or **Not applicable**, with inspected paths and evidence. An uninspected category isn't Pass or Not applicable. Reference one redundancy finding from multiple rows instead of repeating its payload.

Each opportunity needs visible evidence and a concrete clarity/navigation/maintenance/consistency benefit. State paths, problem, proposed change, expected benefit, preserved constraints, risk/unknowns, and useful diff. Tighten prose with qualifiers intact, consolidate only equivalent clauses, replace expensive copies with reachable pointers, or separate reference from active steps. Leave short, clear, intentionally local, well-routed documents alone.

## Selection, changes, and completion

Selections inform a direction; they aren't sign-off. Check selected edits against the ledger and affected routes. Revise or stop if a unique constraint becomes lost, unreachable, or uncertain. Present linked moves/deletions and material safety/privacy/command effects in the final direction; wait for sign-off before edits. Realign only for material departures, not every wording adjustment.

Validate touched pointers/local routes and every ledger constraint; confirm protected non-documentation/generated/per-run/`.picm/` material remains unchanged. Report qualitative results and uncertainty without claiming semantic equivalence or unmeasured token savings. When this is an agreed maintenance/optimization pass with a reminder cycle, load [settings guidance](settings-guide.md) before completion.

For a no-op, provide the required audit, then use exactly this conclusion:

`No worthwhile optimizations found`
