# Workflow Execution Capability Guidance

- Resolve inspectable facts from repository/workspace state, tracker state, commands, logs, local docs, skills, MCP resources/tools, permitted web/network research, and APIs before asking a human.
- Before returning `proceed` for a step, compare the evidence to the step `doneWhen`, the issue's primary intent, and the requested target state. If the evidence only describes missing proof, unavailable access, setup work, or an unperformed target outcome, treat it as blocker evidence unless the step was explicitly scoped to produce that report. If a cheap, in-scope check would answer a likely human concern, run it or state why it was unavailable.
- For improvement or optimization steps, do not claim improvement from activity, implementation, or proxy output alone. Compare evidence against the baseline, evaluation criteria, target or decision threshold, and guardrails when available; otherwise report the claim boundary and remaining measurement work.
- For experiment, validation, benchmark, sandbox, migration, or user-facing workflow steps, report execution-start evidence, execution-result evidence, blocked-before-run evidence, and unavailable checks as separate facts. If the target work did not start, do not present wrapper setup or blocker evidence as target completion unless the step was explicitly scoped to feasibility or blocker reporting.
- When reporting bounded, sampled, partial, or time-limited execution, state the claim boundary: what the run proves, what it does not prove, and do not present evidence from an incomplete target run as completion-quality evidence for the full target.
- If readiness for target work fails, do not proceed on setup evidence alone. Use `replan_same_issue` when the fix remains current-scope work; use `spawn_child_issue` only when the blocker needs its own objective, outputs, checks, and at least one separate-tracking reason such as independent deliverable, evidence bundle, review or integration boundary, materially different responsibility area, or likely multiple AI cycles; use `wait_human` only for approval, credentials, unsafe actions, or judgment.
- Apply the shared blocker-routing rule from `workflow-common`. Use `continuation.strategy="spawn_child_issue"` only for blockers that prevent `doneWhen` and need separate tracking; use `replan_same_issue` when the remaining work still belongs in the current issue.
- Do not use follow-up or recurring schedule to cover unmet `doneWhen`. If the current issue is incomplete, choose same-issue execution, `replan_same_issue`, `spawn_child_issue`, `wait_human`, or `fail` according to the blocker; reserve follow-up for independent post-completion work and recurring for cadence-based future runs.
- For reusable skill blockers, start `continuation.reason` with `Skill resolution required:` and include the capability, why not inline, `alpaca capability list/search`, final `alpaca skill list` refs, source choice or approval needs, dependency install commands that need human confirmation, deps/auth/login, help/version/smoke verification, `requires.skills` update from usable refs, and `alpaca workflow lint`.
- For reusable MCP blockers, include the capability, `alpaca capability list/search`, `alpaca mcp list`, `alpaca mcp catalog list --include-system`, `alpaca mcp search`, safe catalog-backed install status, runtime dependency install commands that need human confirmation, auth/secret/admin/permission handoff steps, `alpaca mcp verify --ref <ref>`, any `requires.mcp` update, and `alpaca workflow lint`.
- Before creating or changing MCP server definitions, verify the current MCP server specification from official docs: `https://modelcontextprotocol.io/specification` and `https://modelcontextprotocol.io/llms.txt`. Check Transports, Tools, Resources, Prompts, Authorization, and relevant changelog notes.
- Check `codex mcp --help` / `codex mcp add --help` and `claude mcp --help` / `claude mcp add-json --help` when command syntax or provider differences matter.
- Hand off only when the remaining decision requires human preference, approval, credentials, permissions, unsafe or irreversible operations, product or operational judgment, or unavailable external information.
