| 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.
