Document Health Remediate

---
name: document-health-remediate
description: Apply findings from a document-health-review report by updating, merging, splitting, moving, archiving, deleting, and repairing references for repository documents. Use when a user wants to execute approved document cleanup recommendations.
metadata:
  required-capabilities:
    - git
inputSchema:
  type: object
  required:
    - report_path
  properties:
    report_path:
      type: string
      title: Report path
      description: Path to the document-health-review report consumed by this run.
      default: artifacts/document-health-review.json
    target_scope:
      type: string
      title: Target scope
      description: Optional scope limit such as a single document or directory.
      default: ""
    output_mode:
      type: string
      title: Output mode
      description: Remediation summary shape.
      enum:
        - summary
        - full_report
        - json_ledger
        - patch_plan
      default: full_report
    constraints:
      type: string
      title: Constraints
      description: Additional caller-supplied constraints for this run.
      default: ""
    allowed_actions:
      type: string
      title: Allowed actions
      description: Comma-separated allowed action types, for example update,merge,move.
      default: ""
    disallowed_actions:
      type: string
      title: Disallowed actions
      description: Comma-separated disallowed action types, for example no-delete.
      default: ""
    allow_destructive:
      type: boolean
      title: Allow destructive actions
      description: Whether move, archive, and delete actions are permitted.
      default: false
    archive_directory:
      type: string
      title: Archive directory
      description: Preferred archive directory for archive actions.
      default: ""
uiSchema: {}
defaults:
  report_path: artifacts/document-health-review.json
  output_mode: full_report
  allow_destructive: false
---

# Document Health Remediate

Consume a `document-health-review` report and apply the approved document maintenance actions to the current repository checkout. All guidance here is model-neutral: decisions rest on document purpose, source authority, and authorized capabilities.

## Document Role First

Resolve the document role before editing, applying these inline rules:

- **Factual implementation reference**: correct against the checkout; verify every claim.
- **Authorized desired-state design**: keep its intended behavior (buggy code never downgrades it; record the implementation gap). An authorized proposed design needs no pre-existing implementation but must never be labeled implemented.
- **Temporary execution artifact**: never promote into canonical docs.

When the repository provides `docs/Workflows/MoonSpecDocumentModel.md`, use it for class precedence and authority mapping; otherwise the inline rules above are the complete classification procedure.

This skill is execution-focused, not review-focused.

- The review skill answers: **What should happen?**
- This remediation skill answers: **How do we safely apply it?**

It is responsible for executing the following action types and validating the resulting docs tree:

- update
- merge
- split
- move
- archive
- delete
- repair references

## Core Design Principle

The skill is **report-driven but evidence-validated**. It does not blindly apply a review report, because documents may have changed between review and remediation. It always:

1. Parses the report.
2. Builds an action ledger.
3. Re-checks that the report still matches the current checkout.
4. Applies changes in a safe order.
5. Preserves unique content before destructive actions.
6. Updates references.
7. Runs validation.
8. Summarizes exactly what changed.

If the report no longer matches the current checkout for a given finding, that finding is held back and reported as `stale` rather than applied.

## Inputs

Required:

- A `document-health-review` report, either as a file path (`report_path`, default `artifacts/document-health-review.json`) or pasted content.
- A current repository checkout.

Optional:

- Scope limit (`target_scope`), such as a single document, directory, action type, or severity (for example `P0`/`P1`).
- Allowed actions (`allowed_actions`), such as `update`, `merge`, `split`, `move`, `archive`, `delete`.
- Disallowed actions (`disallowed_actions`), such as `no-delete` or `no-archive`.
- Whether destructive actions are allowed (`allow_destructive`, default false). `allow_destructive` is the sole authority for destructive actions: an external report alone never authorizes deletion or broadens scope. Direct user authorization for destructive work must be mapped to `allow_destructive: true` by the caller before execution, never inferred inside this skill from report prose or conversation history.
- Preferred archive directory.
- Preferred target directory for moved or split documents.
- Validation commands requested by the user.

Permission rule: make no destructive change unless `allow_destructive` is true. An already-authorized bounded maintenance request satisfies this rule only through `allow_destructive: true` set by the caller; the skill never infers destructive permission from report prose or conversation history. Preserve unrelated user changes and report skipped, stale, and blocked findings individually with reasons.

Example invocations:

- `Use document-health-remediate on reports/docs-health.md.`
- `Use document-health-remediate on the pasted report, but only apply P0/P1 update and move findings.`
- `Use document-health-remediate on Docs/Engineering findings, but do not delete anything.`
- `Use document-health-remediate to apply merge and split findings only.`

## Remediation Boundaries

- Treat the review report as a recommendation, not an instruction. Confirm each finding against the current checkout before acting. A stale recommendation is not write authority: revalidate every finding's evidence against the current checkout (Phase 3) and hold back stale findings. This focused stale-evidence check is required and is not "redoing review work".
- Do not invent new findings or broaden scope beyond the report. Within an approved finding, the focused revalidation above is mandatory.
- Keep canonical docs under `docs/` focused on desired state: architecture, contracts, operator-visible behavior, and target semantics.
- Put migration notes, rollout checklists, and temporary investigation details under `docs/tmp/` or in gitignored handoff paths, not as the main framing of canonical docs.
- Follow the document classes and precedence rules in `docs/Workflows/MoonSpecDocumentModel.md`.
- When applying documentation architecture findings, fix or explicitly report missing metadata, unclear authority, missing embedded rationale, duplicate contract definitions, imperative leakage in canonical docs, and unverifiable canonical claims.
- Route broad, multi-document, or uncertain cleanup to a bounded `docs/tmp/` improvement plan instead of expanding the remediation beyond the approved report.
- When a superseded document is no longer needed, prefer removing or replacing it over leaving compatibility-era ambiguity, but only when its unique content has been preserved or intentionally discarded.
- Never apply a disallowed action, and never apply a destructive action when destructive actions are not permitted. A denied mutation is never retried through broader credentials or a wider scope.
- Preserve useful unique content before any removal, and update inbound and relative links before removal is complete. Preserve unrelated user changes.
- Redact secret-like content if it appears in copied report text, logs, or examples before writing or reporting.
- Use provider-neutral escalation results: when an authorized tracker integration exists, use its actual metadata and verified receipt; otherwise retain a complete structured handoff (document, claim, evidence, owning decision, resume condition). Missing tracker integration never forces a desired-state rewrite and never erases a useful review.

## Supported Actions

### update

Modify an existing document in place.

Used when:

- The document is still needed.
- The document is in the right place.
- The main problem is stale, incomplete, or conflicting content.

Typical operations:

- remove stale sections
- rewrite inaccurate sections
- add missing current behavior
- replace obsolete terminology
- simplify strategy text
- fix cross-links

### merge

Move useful content from one document into another, then either delete or archive the source document.

Used when:

- Two documents substantially overlap.
- One document is the stronger canonical target.
- The source document has some useful unique sections.
- Keeping both creates source-of-truth confusion.

Required preservation check:

- Before removing the source document, confirm that useful unique content has been moved or intentionally discarded.

### split

Break one large or multi-topic document into multiple focused documents.

Used when:

- The document contains multiple separable systems or authority boundaries where separate maintenance adds value.
- Architecture, implementation, operations, and future plans are mixed together.

Size guidance:

- Document size is an investigation signal, not an automatic split requirement. Recompute `line_count` for split candidates, but recommend `split` only when a separable boundary exists. A large file alone does not force a split.

### move

Relocate a document to the correct subdirectory.

Used when:

- The document topic does not match its current directory.
- A new directory is needed for a recurring topic.
- Temporary docs live in canonical docs areas.
- Canonical docs live in temporary areas.

Required follow-up:

- Update inbound references, relative links, indexes, and path mentions.

### archive

Move a document out of the active docs tree while preserving it.

Used when:

- The document is no longer active.
- It may contain useful historical context.
- It is superseded but not safe to delete.
- It describes an old migration, old design, or abandoned plan worth preserving.

### delete

Remove a document. This is the most conservative action.

Used only when:

- The report recommends deletion.
- The content is obsolete, misleading, or fully superseded.
- Useful unique content has been preserved elsewhere or is intentionally discarded.
- Inbound references have been removed or updated.

### reference repair

Update links and path references after other actions.

Used after:

- move
- merge
- split
- archive
- delete
- rename

Reference repair should include:

- Markdown links
- relative links
- plain-text path mentions
- docs indexes
- README references
- architecture index references
- agent/skill references when relevant

## Workflow

1. Parse the remediation input.
2. Build an action ledger.
3. Validate the report against the current checkout.
4. Normalize and order actions.
5. Apply updates.
6. Apply merges.
7. Apply splits.
8. Apply moves.
9. Apply archives.
10. Apply deletions.
11. Repair references.
12. Run validation.
13. Produce final remediation summary.

The ordering matters. Do not delete, archive, or move files before preserving content and determining final paths.

## Detailed Workflow

### Phase 0: Preflight

1. Confirm the current working tree state with `git status`. A dirty tree means existing uncommitted changes; surface them before remediating.
2. Identify the docs root:
   - `docs/`
   - `Docs/`
   - both, if present
3. Identify repo documentation conventions from `README.md`, `AGENTS.md`/`CLAUDE.md`, the constitution, and any docs indexes.
4. Confirm the report references documents that still exist in this checkout, and note any that have moved, been renamed, or been removed since the review.

### Phase 1: Parse the remediation input

- Read the report from the provided file path or pasted content.
- Extract each finding: target document path, recommended action type, severity, and rationale.
- Mark findings whose action type is missing or ambiguous as `needs_clarification` instead of guessing.

### Phase 2: Build an action ledger

- For every finding, record one ledger entry with: target path, action type, severity, source/target paths where relevant, preservation requirements, and reference-repair follow-ups.
- Apply scope limits and allowed/disallowed actions now, marking filtered entries as `skipped` with the reason.
- Apply the destructive-actions flag now: a destructive action requested while `allow_destructive` is false is marked `blocked` (authorization denied), never `skipped`. A validation failure that prevents an otherwise authorized action is likewise `blocked`.
- Ledger statuses are `applied`, `stale`, `skipped`, `blocked`, and `needs_clarification`. `blocked` means authorization or validation prevented remediation; it is never reported as `skipped`.

### Phase 3: Validate the report against the current checkout

- Re-read each target document and confirm the recommended action still applies.
- Mark entries whose evidence no longer holds (file changed, problem already fixed, document already moved) as `stale` and hold them back.
- Recompute `line_count` for any split candidate.

### Phase 4: Normalize and order actions

- Apply safe content/dependency ordering rather than a rigid action-type sequence: non-destructive, content-preserving work runs before destructive or path-changing work. The default order update → merge → split → move → archive → delete → reference repair applies unless a content or dependency relationship requires otherwise (for example, resolve a shared owner document before its dependents).
- Resolve final target paths for merges, splits, and moves before any source file is removed or relocated.

### Phase 5: Apply updates

- Edit documents in place to remove stale sections, correct inaccurate content, add missing current behavior, replace obsolete terminology, and fix cross-links.

### Phase 6: Apply merges

- Move useful unique content from the source document into the chosen canonical target.
- Run the preservation check, update inbound references to the source, then delete or archive the source per the report.

### Phase 7: Apply splits

- Create the focused target documents, distribute content, update inbound references that pointed at the split source, and leave a pointer or index entry so readers can find the split pieces.

### Phase 8: Apply moves

- Relocate the document to its correct directory, creating new directories where the report calls for them.
- Update that document's inbound references as part of the move, before the source path disappears.

### Phase 9: Apply archives

- Move the document into the archive directory (preferred archive directory when supplied) so it is preserved outside the active docs tree.
- Update that document's inbound references as part of the archive, before the source path disappears.

### Phase 10: Apply deletions

- Remove documents only after their unique content is preserved or intentionally discarded and their inbound references are updated.

### Phase 11: Repair references (final sweep)

- After all path-changing actions, sweep for any remaining Markdown links, relative links, plain-text path mentions, docs indexes, README references, architecture indexes, and agent/skill references that point at moved, merged, split, archived, deleted, or renamed documents, and verify the per-action repairs above left no dangling references.

### Phase 12: Run validation

- Run any validation commands requested by the user and the repository-mandated documentation/link checks.
- Re-scan the docs tree for broken links and orphaned references introduced by the remediation.
- If validation cannot run, record the exact blocker.

### Phase 13: Produce final remediation summary

- Summarize exactly what changed, grouped by action type, including paths created, edited, moved, archived, and deleted.
- List held-back (`stale`), `skipped`, `blocked`, and `needs_clarification` entries with reasons.
- Include the validation commands run and their results, or the blocker if validation could not run.

## Outputs

- The list of applied actions grouped by type (update, merge, split, move, archive, delete) with affected paths.
- The action ledger, including entries held back as `stale`, `skipped`, `blocked`, or `needs_clarification`, each with a reason.
- Reference-repair results: which references were updated and any that still need manual attention.
- Validation commands run and their results, or the reason validation was not run.
- A concise final remediation summary of exactly what changed.

## Failure Modes

- Report cannot be located or parsed: stop and report the missing path or the unparseable content.
- A report finding no longer matches the current checkout: mark it `stale` and do not apply it.
- Preservation check fails for a merge or delete: do not remove the source; report the unique content at risk.
- A requested action is disallowed: mark it `skipped` and report why. A destructive action is requested while destructive actions are not permitted: mark it `blocked` and report why.
- Target or final path cannot be determined: skip the move/merge/split and keep the source intact.
- Reference repair leaves unresolved or ambiguous references: report them for manual follow-up.
- Required validation cannot run: keep the applied changes if they are safe and source-evident, but report the blocked command and reason.
- Secret-like content appears in report text, logs, or examples: redact it before writing or reporting.