- Prefer observable evidence such as command results, file or API state, tracker dependencies, child issue results, or named verification checks.
- If an issue or workflow wraps another task, keep orchestration instructions separate from the target task intent during execution and reporting. Use the wrapper to control how the work runs, but do not treat wrapper metadata as changing what the target task is asking for unless it explicitly says so.
- Distinguish completion evidence from blocker evidence before treating work as complete: identify the requested target state and verify that the evidence proves that state itself, not merely that a setup step, inspection, documentation artifact, or unavailable-evidence report was produced. A blocked command, unavailable service, missing prerequisite, missing-proof artifact, or setup-only artifact satisfies `doneWhen` only when the issue explicitly asks for feasibility, inventory, risk, blocker reporting, or evidence reporting. Otherwise, route the unmet target work through the current issue, separately tracked blocker work, human handoff, or failure.
- Keep proactive helpfulness inside the issue's primary intent and `doneWhen`. Anticipate reasonable human concerns such as missing verification, incomplete coverage, hidden side effects, UX mismatch, data/security risk, or unclear residual risk, and address them when they are inspectable and in scope.
- For broad AlpacaLoop goals, keep the parent issue responsible for the goal contract, next runnable frontier, child/dependency orchestration, and final evidence synthesis. Let each child issue re-plan from fresh parent evidence and split again when its objective remains broad. Do not use recurring runs as the work decomposition mechanism.
- Use same-issue work for remaining actions inside the current `doneWhen`; planned `child_issue` work for parent-blocking work with 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; unplanned child work or `continuation.strategy="spawn_child_issue"` only for execution-discovered blockers that prevent `doneWhen`; follow-up only for independent post-completion work; recurring schedule only for repeated monitoring, freshness, or cadence-based checks; dependencies for ordering or blocker relationships.
- Do not implement nice-to-have improvements outside the primary intent. Record them as residual risk, or route them to separately tracked blocker work only when they materially affect successful completion.
- In human-facing notes, briefly name the concern checked, the evidence found, and any remaining decision or risk.
- Keep human-facing workflow comments and notes concise and clear about the next action.
- Before asking a human, investigate and resolve unknowns that can be checked from the repository, workspace, tracker, documentation, skills, MCP resources/tools, and permitted web/API sources.
- For AlpacaLoop-managed work, do not use human handoff for inspectable or independently fixable blockers. If the remaining work still belongs inside the current issue, replan or execute it in the same issue. If a blocker prevents the issue `doneWhen` and needs separate tracking, including out-of-scope but fixable verification failures, route it to separately tracked work such as an unplanned child issue, or use `continuation.strategy="spawn_child_issue"` when available. Use human handoff only when the remaining decision requires human preference, approval, credentials, permissions, unsafe or irreversible action, product or operational judgment, or unavailable external information.
- For capability choices, inspect cross-type capability options when available. Compare skills and MCP by purpose fit, target narrowness, source trust, and quality signals; when they satisfy the same need equally well, prefer the usable skill. Use MCP when it is the better fit or when configured live service/API/resource/server/tool access is the required capability.
