# Workflow Planning Capability Guidance

- For each non-child task step, start instructions with one short working-stance sentence that names the concrete perspective, audience, primary-intent contribution, and evaluation axis implied by the issue or template. Include the human concern the step reduces when that concern is material.
- Plan only the proactive checks that make the final result trustworthy for the primary intent; do not add steps for speculative convenience, unrelated polish, or implementation scope that the issue did not ask for.
- Keep plan fields schema-valid: omit mode-disallowed fields, and split long commands, settings, or evidence requirements into separate list items.
- Keep each planning run's `plan.steps` to at most 10 total steps across `task`, `workflow_ref`, and `child_issue`. Concretize only the next runnable frontier and required integration checkpoints; do not split work only to fill the limit.
- When target execution depends on setup, assets, permissions, commands, external state, or shared prerequisites, plan a readiness step before target execution or dependent `child_issue` fan-out, and make later steps depend on its evidence.
- When target work could materially benefit from existing implementations, libraries, templates, tools, prior issue evidence, or OSS projects, plan a bounded reuse-first investigation before design or implementation. Prefer repository-local and already-installed sources first; use external sources only when local evidence is insufficient, the information must be current, or the workflow quality bar justifies it. Make adoption depend on project fit, license or terms compatibility, security/privacy risk, maintenance signals, dependency weight, and repository-verifiable checks.
- When deriving `objective` and `doneWhen`, preserve the requested target state and the evidence source needed to prove it. Do not weaken the contract into producing a plan, note, setup artifact, or unavailable-evidence report unless the issue explicitly asks for that kind of report.
- For experiment, validation, benchmark, sandbox, or migration work, keep target work distinct from wrapper work. Preserve source inputs that must be executed or evaluated, plan setup and evidence collection separately from target execution, and do not let setup-only steps satisfy the target outcome.
- When the issue or workflow requires comparing alternatives, preserve a shared evaluation basis before splitting work. Plan independent candidate work only when inputs, constraints, and verification evidence can remain comparable, and add a dependent synthesis step to compare evidence, choose or defer, record rejected-option reasons, and name residual risk.
- For bounded, sampled, partial, or time-limited execution, plan reporting or decision steps that state what observed evidence can prove, what remains unproven, and whether the conclusion is completion-grade, comparison-grade, or partial-confidence only.
- Use `child_issue` steps for alternatives only when each alternative needs separately tracked planning, outputs, completion checks, multiple AI cycles, or a materially separate review boundary. Keep small comparable alternatives in the same workflow plan.
- Use `child_issue` for broad issue-surface goals when the next runnable frontier contains parent-blocking work with its own objective, outputs, completion checks, and at least one separate-tracking reason: independent deliverable, evidence bundle, PR or review boundary, materially different responsibility area, or likely multiple AI cycles. Keep a single-theme implementation, local fix, or tightly coupled verification bundle in same-issue task steps.
- When splitting target work into child issues, include the exact target input or a stable reference to it, the wrapper boundary, the child deliverable and outputs, and doneWhen evidence for target execution start/result or for a blocked-before-run condition that the parent can treat as no-score, defer, or blocker.
- For broad or abstract goals on issue workflow surfaces, use the parent issue to establish the goal contract: the valuable end state behind the request, primary intent, audience or consumer, deliverable or target state, quality bar, observable success evidence, constraints, unknowns, assumptions whose failure would make the work ineffective, shared readiness, dependency order, integration responsibility, and next runnable frontier. Use 5W1H as internal coverage, not as a required output format. When an inspectable assumption could make downstream work ineffective, materialize that validation as an early frontier before dependent implementation. Materialize only the frontier work as same-issue tasks or `child_issue` steps with dependencies, and leave later work coarse until it becomes actionable.
- For broad new service, app, automation, API, integration, or business/product requests, do not make implementation the first proof of success. Plan an early evaluation gate for unverified success assumptions such as target users, demand, acquisition or adoption path, differentiation, trust/safety, data/privacy, authentication, operations, acceptance evidence, and constraints whose failure would make the build ineffective.
- In hierarchical issue plans, a `child_issue` is a seed for the next independently planned frontier, not a fully expanded downstream plan. Each child planning run should inspect the parent result, preserve the child objective, and decide whether to execute same-issue tasks or split again.
- Do not make one child issue absorb multiple unrelated responsibility areas only to avoid deeper hierarchy. Use deeper `child_issue` steps when the child objective remains broad and the next frontier has independent deliverables, evidence bundles, or review boundaries.
- For `replan` and `revise_plan`, return `planPatch` as an incremental patch over the current plan instead of rewriting the full plan. Set `planPatch.basePlanRevision` to the current workflow state's `planRevision`, not the workflow state `version`. Omit unchanged work, use `move_step` only for list-position-only changes, use `update_step.dependsOnStepIds` when execution order semantics change, preserve completed evidence and materialized child/workflow_ref metadata, and use explicit child or workflow_ref decisions when parent relationships or reusable workflow expansions must change. Return `wait_human` instead of `planPatch` when changing a started materialized child, completed evidence, or workflow_ref subtree is unsafe or ambiguous.
- When plan review feedback identifies a capability-sensitive step or reusable skill/MCP gap, revise the plan so dependent work either uses a fitting available capability, depends on a skill-resolution or MCP-resolution child before execution, or records a concrete reason why no specialized capability is needed.
- For each capability-sensitive step, carry catalog evidence into visible plan fields when catalog commands are available: name exact selected skill refs, usable installed MCP refs, MCP catalog ids, or search result ids in the step `instructions`, `doneWhen`, or `outputs`. Mark each named candidate as selected, deferred to skill/MCP resolution, rejected, or intentionally not needed; do not leave only generic labels such as "SEO MCP", "Figma skill", "Google integration", or "Cloudflare capability".
- Do not promote search result ids or MCP catalog ids into `requires.skills` or `requires.mcp`. Use them as planning evidence or resolution inputs until `alpaca skill list`, `alpaca mcp list`, or `alpaca mcp verify --ref <ref>` shows a usable required ref.
- For abstract improvement or optimization goals, derive an evaluation contract before action steps: improvement target, current state or baseline to inspect, metric definition or evaluation axis, source of truth, measurement window when relevant, target or decision threshold, guardrails or non-goals that prevent proxy success, unknowns, and claim boundary. If the issue body lacks these, make the next runnable frontier obtain or clarify them before planning work that claims improvement.
- When planning a parent with `child_issue` steps, keep the parent responsible for integrating child results, dependency status, and final evidence before the parent `doneWhen` is satisfied.
- When planning AlpacaLoop-managed work, encode independently fixable blockers as investigation or task work instead of `humanHandoffWhen`; on issue workflow surfaces, use `child_issue` only when the blocker needs its own objective, outputs, completion 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.
- Treat recurring schedules as workflow state for repeated monitoring, freshness, or cadence-based checks. Do not use recurring runs as the default way to decompose or advance a broad goal; use parent orchestration, child issues, and dependencies instead. If repeated attention is useful but no justified cadence exists, keep the repeat loop in the issue plan, evidence, or human-facing body instead of inventing schedule state.
- When planning or replanning may duplicate parallel work, miss prior decisions, or continue recurring work, inspect memory in the cheapest useful order. Start with the current open-work snapshot (`alpaca issue list --state open --view compact --format text --limit 20`). Only when the target issue's own history is needed, inspect it with bounded related history (`alpaca issue show --issue <id> --children 1 --limit 5 --format text`); use `--children all --limit all` only when the bounded output leaves a concrete unanswered question. For recent completed history, prefer a small closed-issue snapshot such as `alpaca issue list --state closed --view compact --format text --limit 10`, adding existing label, assignee, state, or day filters when they materially reduce output. If compact snapshots do not identify the relevant issue and the goal has a distinctive title keyword, use `alpaca issue search --title "<keyword>" --state all --limit 10 --format text`; use `--query` only when title search is insufficient and broader provider search is worth the extra noise.
- Treat memory command output as evidence for the plan, not as text to preserve. Carry forward only issue ids, active ownership, relevant prior decisions, blocked or duplicate work, and verification facts needed to choose efficient next actions. Do not search broad repository history or paste long history into plan fields unless the compact snapshots and target issue history are insufficient.
- Do not plan declared required skill or MCP gaps as ordinary `child_issue` steps. AlpacaLoop handles them before worker launch according to `approvals.requirementsSetup`, either through setup issues or human confirmation.
- If a newly discovered reusable capability gap is not a declared required skill or MCP gap and blocks safe completion, inspect `alpaca capability list` and `alpaca capability search "<capability>"` first when available, then decide the source by purpose fit, target narrowness, source trust, and quality signals. When a skill and MCP satisfy the same need equally well, prefer `alpaca skill create --prompt <gap request>` or the skill-resolution path. Use `alpaca mcp create --prompt <gap request>` only when MCP is the better fit or configured live tool/resource/API/server access is the core missing capability. Do not create both resolution types for the same gap.
- Use ordinary `child_issue` only when the missing capability is repo-specific, tool-specific, domain-specific, likely to recur, independently verifiable, and not better represented by the skill/MCP resolution commands.
- For newly discovered reusable capability gaps that need separate tracking, route to the dedicated skill-resolution workflow when a usable or creatable skill is the best fit or ties with MCP; route to the dedicated MCP-resolution workflow only when MCP is the better fit or live external service, API, resource, server, or configured MCP tool access is the core missing capability.
- The dedicated resolution workflow owns detailed discovery, install or enablement, dependency setup with human-confirmed commands, verification, requirements updates, and lint.
- Do not create skill-resolution or MCP-resolution child issues for one-off work, ordinary implementation steps, convenience improvements, or declared required skill/MCP availability gaps.
