agentplane-task-closure-recovery

name	agentplane-task-closure-recovery
description	Use when Agentplane task completion, direct finish, branch_pr integration, hosted-close, close-tail PRs, PR metadata, dirty task artifacts, or remote branch divergence need diagnosis or recovery.

Agentplane Task Closure Recovery

Use This Skill When

• agentplane finish, integrate, task hosted-close, or task hosted-close-pr fails.
• A task-close/* PR is duplicated, closed, obsolete, or still open after hosted closure.
• pr open fails because the remote branch already exists.
• A task is DONE locally but artifacts, branch state, or hosted closure disagree.
• Direct-mode finish is blocked by unrelated dirty task artifacts.

First Classification

1. Read workflow mode:

agentplane config show

2. Identify the task state:

agentplane task show <task-id>
agentplane task verify-show <task-id>
git status --short --untracked-files=no
git rev-parse --abbrev-ref HEAD

3. Query incident advice:

agentplane incidents advise <task-id>

Direct Mode

Expected close path:

agentplane verify <task-id> --ok --by CODER --note "..."
agentplane finish <task-id> --author CODER --body "Verified: ..." --result "..." --commit <git-rev>

If finish is blocked:

• Check whether dirty files belong to the active task or another active task.
• Check whether policy/incident mirrors were generated by finish and need allowed staging.
• Do not manually edit .agentplane/tasks.json.
• Do not use branch_pr close-tail commands in direct mode.

Branch PR Mode

Classify before recovery:

• Implementation PR branch: task/<task-id>/<slug>
• Closure PR branch: task-close/<task-id>/<sha>
• Base-side closure already landed: task README has DONE status and close commit exists on main.

Useful commands:

gh pr list --state all --head "task-close/<task-id>/<sha>"
gh pr view <number> --json state,mergedAt,headRefName,baseRefName,url
git ls-remote --heads origin "task/<task-id>/*"
git ls-remote --heads origin "task-close/<task-id>/*"

Known Recovery Patterns

Remote Branch Already Exists

If pr open fails after trying to push:

1. Compare local branch tip to the remote branch tip.
2. If they match, continue PR creation instead of forcing another push.
3. If they differ, stop and classify divergence before overwriting anything.

Obsolete Close Tail

If hosted closure already landed on main:

1. Treat the canonical close commit on base as a no-op condition.
2. Do not create a new manual close-tail PR.
3. Clean up only branches/PRs that are proven obsolete.

Dirty Base After Closure

If close paths wrote task artifacts or incident mirrors:

1. Confirm the dirty paths are allowed for the closure operation.
2. Stage only closure-scoped artifacts.
3. Keep unrelated active task dirtiness untouched.

Verification

Minimum evidence:

• task state before and after
• branch/PR state before recovery
• exact command that changed state
• final git status --short --untracked-files=no
• a focused regression test when code changed

Record recovery facts in the task README Findings; promote reusable external incidents only through the incident workflow.