reconcile-docs

name	reconcile-docs
description	Close the docs/backlog side of a lap: fix behavior docs the change made wrong; delete satisfied issues/plans; fix backlinks. Use after implement, before draft-commit — not for AGENTS/.agents context drift.
disable-model-invocation	true

Reconcile docs

Close the human / behavior docs + issue/plan ledger side of a lap after behavior moved. Chat is not the backlog; delete-on-ship keeps the ledger true.

Loop context: .agents/context/development-loop.md.

Issues: docs/issues/README.md. Plans: docs/plans/README.md (when present); living plans may still live under .cursor/plans/.

Not this skill

Skill	Surface
This skill (reconcile-docs)	App/behavior READMEs, docs/issues/, docs/plans/, plan links
reconcile-context	AGENTS.md, .agents/context/, discovery / link health

Run reconcile-context separately when agent routing or context modules drifted. Do not fold context work into this skill.

Hard rules

• Never invent new features while reconciling. Fix stale prose and ledger state only; out-of-scope gaps → file-issue.
• Delete-on-ship — no closed/ archives. Git history is the archive.
• Acceptance gate — if acceptance is not met, do not delete the issue or plan; surface what remains.
• Protected paths — never write a path listed in protected-paths.md without confirmation. docs/ is freely editable except listed paths. Propose a patch and wait; if declined, keep the issue/plan and its backlink rather than leave a broken link.
• This skill does not ship (no commit/push). Hand off to draft-commit when authorized — see constraints.md#commit-and-ship. Never cluster-mutate.

When to run

• After an implement lap, before draft-commit (when that skill exists).
• When the operator asks to close docs/backlog for a shipped change.
• Same change set as the fix whenever possible (issue/plan delete + doc fixes land with the behavior change).

Workflow

- [ ] 1. Identify touched behavior (diff / Launch brief / linked issue+plan)
- [ ] 2. Update behavior docs that the change made wrong (READMEs, runbooks)
- [ ] 3. Check acceptance on linked docs/issues/<slug>.md
- [ ] 4. Check acceptance on linked docs/plans/<slug>.md and/or .cursor/plans/
- [ ] 5. If met → delete those files; if not → keep and list remaining gaps
- [ ] 6. Fix backlinks (other docs, plans, issues that pointed at deleted paths)
- [ ] 7. Repo-wide link check (`check_links.py --all`)
- [ ] 8. Report what changed / what stayed / blockers

Behavior docs

Update only docs that describe current behavior and are now wrong. Do not narrate the fix ("previously broken…"). Prefer adjacent READMEs over inventing new doc trees. Tunable config stays in manifests (GitOps SoT). Never write a protected path: if one is affected, return a proposed patch and wait.

Protected docs

If a required edit (behavior doc or a backlink before deleting an issue/plan) hits a path in protected-paths.md:

• Approved — apply the patch, then complete any deferred deletions.
• Declined — do not apply; keep the issue/plan files and their backlinks.
• No patch — proceed.

Homelab does not currently list docs/ paths as protected; still honor the list if it grows.

Issues (docs/issues/)

• Satisfied acceptance → delete docs/issues/<slug>.md in this change set.
• Not satisfied → leave the file; report remaining acceptance / feedback-loop gaps. Optional: set status / notes if the operator asked — do not fake closure.
• Skip README.md, _template.md.

Plans (docs/plans/ and .cursor/plans/)

• Satisfied plan for this lap → delete docs/plans/<slug>.md when that ledger is in use.
• If the living plan lived under .cursor/plans/, delete (or clear) that plan file the same way and note in the report that .cursor/plans/ was the plan surface.
• Partial plans: do not delete; uncheck nothing retroactively to fake done — surface leftover checkboxes.

Backlinks

After deletes, grep for the old paths/slugs and fix or drop links in remaining docs, issues, and plans. Broken links left behind are unfinished reconcile.

Link check

Default check_links.py covers the agent context surface only. After doc / issue / plan deletes, run repo-wide so backlinks elsewhere do not rot:

python3 .agents/skills/reconcile-context/scripts/check_links.py --all

Do not fold full reconcile-context into this skill — only the --all link pass. Hand agent-tree drift to reconcile-context.

Output format

## Docs reconciliation

**Behavior docs updated:** <paths or none>

**Deleted (acceptance met):**

- docs/issues/<slug>.md
- docs/plans/<slug>.md # and/or .cursor/plans/…

**Kept (acceptance not met):**

- <path> — <what's left>

**Backlinks fixed:** <paths or none>

**Hand off:** reconcile-context if AGENTS / `.agents/` drifted; else draft-commit

**Link check (`--all`):** <pass | N fixed>

If nothing needed reconcile, say so in one line and stop.

Homelab constraints

• This skill does not ship (no commit/push). Ship via draft-commit when authorized — constraints.md#commit-and-ship.
• Never cluster-mutate as part of reconcile-docs.
• No secrets in doc or issue bodies.
• Protected paths still need confirmation unless the operator already ordered this reconcile (summarize first). Prefer leaving agent-tree edits to reconcile-context; any protected docs/ path uses the same confirmation gate as above.