# Workflow Closing Follow-up Recommendation Guidance

- This guidance applies during `workflow_closing`. Audit the source request before recommending follow-up: compare the latest user instructions, source issue body, execution contract, workflow plan, step results, PR/merge result, and evidence. Do not treat plan completion alone as proof that the user's original request is fully delivered.
- Recommend follow-up only when the source issue can close as a coherent completed tranche and the remaining work is independently trackable after close. Do not use follow-up when the source result is unsafe, broken, false, has unmet `doneWhen`, lacks evidence needed to prove the target state, or cannot honestly close; use `replan_same_issue`, `spawn_child_issue`, `wait_human`, `fail`, recurring schedule, child, or unplanned paths as appropriate.
- Consider only same source issue follow-up candidates. Do not aggregate, duplicate, or recreate follow-up items generated inside child issues; child issues publish their own follow-up recommendations when they close.
- Classify every item with `category: "mainWork"` or `category: "maintenance"`. Use `mainWork` for work needed to continue the source issue's main requested work, including unimplemented parts, stub-to-real completion, broader validation, post-release checks, cleanup, docs, or operational follow-through. Use `maintenance` for work that improves future AI execution or repository workflow quality, including workflow templates, worker environment guidance, Codex/Claude configuration, skills, MCP, prompts, or reusable process capture.
- Prefer `recommended: true` when one or more follow-up items are independent, actionable, and useful after the source closes, such as remaining main requested work, hardening, cleanup, additional coverage, documentation, monitoring, performance improvement, future automation, workflow, skill, MCP, or template improvement, or a follow-on investigation.
- Prefer `recommended: false` when the possible next work is speculative, too vague to track, already covered by the current issue, not worth a separate issue, or requires human product judgment before it can be framed. Return `items: []` and make `reason` explain why no independent post-completion issue is worth creating.
- Do not restate the source completion result except when it is needed to bound the follow-up request.
- If source detail inspection is needed, prefer `alpaca issue show --issue <source-id> --view followup --format text`; give special weight to post-completion user comments because they may be explicit follow-up instructions. If that view includes child issue information, use child results only as completion evidence for the parent and exclude child-generated follow-up items from the parent recommendation.
- Before finalizing `followupRecommendation`, inspect available follow-up workflow templates when feasible with `alpaca workflow list --include-system --target followup --format json`. Treat `followup.preferredWorkflowTemplates` as the highest-priority templates to consider, not as an allowlist. If the cap still has room or a preferred template does not fit, you may also choose a listed follow-up template or `no_template`; `no_template` is always an available choice. Do not reject useful independent work only because no preferred template fits, the list is empty, or the command is unavailable.
- When `recommended` is true, first list the possible independent follow-up items, merge candidates with the same purpose, deliverable, or verification evidence, then order them by value and independence. For `followup.proposalApproval: "auto"`, return at most `followup.maxIssuesPerSource.mainWork` mainWork entries and at most `followup.maxIssuesPerSource.maintenance` maintenance entries. For `followup.proposalApproval: "confirm"`, return all useful candidates; the configured maximum does not cap candidates waiting for human confirmation. For `followup.proposalApproval: "confirm_if_needed"`, set item `proposalApproval: "auto"` only for clearly necessary candidates that should be created automatically; set `proposalApproval: "confirm"` or omit it for uncertain candidates that should wait for human review. The configured maximum caps only the `auto` items in `confirm_if_needed`. Do not treat the configured maximum as a quota, and leave slots unused when no useful independent issue exists.
- Each item must have `category`, a concise `title`, a `body` of 1000 characters or fewer, and a `reason`. In `body`, state the independent post-completion objective, why it can be tracked separately after the current close, and observable completion evidence; prefer compact bullets or short sentences over copied source context. When the follow-up should run once later or recur, write the timing, cadence, first-run expectation, and finite stop condition in natural language inside `body`; do not add structured scheduling fields. Set optional `workflowTemplate` only when a specific preferred/listed template path clearly fits, or to `no_template` when the built-in default follow-up workflow is the right fit. Omit `workflowTemplate` when the normal follow-up selection fallback should decide. Do not use `auto` or `auto_select` in `workflowTemplate`.
