Project Reconciliation

Project Reconciliation

Intro

Use /pk-reconcile to turn the recurring cleanup request into one guarded workflow. It owns the combined migration, pk-doctor, issue, and pull-request queues; the specialist skills continue to own their individual remediations.

Overview

Select a scope

Reconcile in order

1. Migrations. Apply or continue unambiguous migrations; reject clearly malformed no-op migrations. Ask before policy-changing, destructive, ambiguous, conflicting, or externally blocked changes.
2. Health. Run pk-doctor; build a queue from every ERROR, WARN, and actionable INFO. Use the owning tool to fix safe, unambiguous findings, then rerun the doctor.
3. Repository. Run pk-repo-reconcile in plan mode. Resolve issues only with evidence and merge only non-draft pull requests that satisfy branch protection and checks. Obtain the existing confirmation tokens before external close or merge actions.
4. Report. Rerun the selected checks. State what was fixed, what remains, the owner or blocker for each remaining item, and the next exact action.

/pk-resume invokes pk-reconcile session-start before generating its briefing. It does not repeat the reconciliation logic or silently close an issue or merge a pull request at session start.

Gotchas

• Treating every finding as safe to auto-fix. Errors, warnings, and actionable INFO are a queue, not blanket permission. Preserve the owning skill's confirmation and state-machine rules.
• Closing GitHub issues because a related change exists. Link concrete evidence and use the repository tool's required confirmation; otherwise leave a proposed resolution in the report.
• Merging a pull request merely because it is open. Draft state, missing checks, unresolved comments, and branch protection remain hard blockers.
• Running full repository mutation during pk-resume. Session start may inspect GitHub state, but external close and merge actions require the explicit full reconciliation scope and its confirmations.
• Reporting doctor totals without action totals. A zero-WARN result is not clean if actionable INFO remains. Always account for both queues.
• Moving migration files by hand. Use migration-management tools so validation, state transitions, and audit events remain consistent.

Full reference

Completion contract

Report each selected queue using this shape:

Scope:
Resolved:
Remaining:
Blocked or confirmation-required:
Recheck evidence:
Next action:

all is complete only when every selected item is fixed, explicitly deferred with a reason, linked to evidence or a tracking item, or reported as blocked by missing authority or external state.

Anti-patterns

• Replacing specialist remediation with a generic script. Delegate to the migration, doctor, and repository owners; this skill coordinates order and reporting only.
• Treating a plan as execution. A dry run is valuable but does not resolve work. Say clearly which mutations were applied and which require approval.
• Hiding an external blocker. Missing authentication, branch protection, or a required reviewer is an actionable result, not a clean outcome.

Cross-references

• migration-management — migration state transitions
• pk-doctor — health finding remediation
• repo-management — guarded issues, pull requests, commits, and pushes