---
title: Decision Guide
description: Coordination choice guidance for AlpacaLoop workers.
relatedDocs:
  - issues
  - workflow-templates
  - capabilities
  - maintenance
---

# AlpacaLoop Decision Guide

Use this guide when an AlpacaLoop worker needs to choose the next coordination action. This guide is intentionally about choice points only. It must not redefine workflow schemas, child issue fields, decision JSON, labels, or canonical workflow state.

## Authority Order

Follow these sources in order:

1. System and developer instructions.
2. Repository instructions such as `AGENTS.md` and active repo-local skills.
3. AlpacaLoop workflow context, decision contract, canonical workflow state, labels, and dependencies.
4. The active workflow template.
5. This guide.

If this guide conflicts with the worker decision contract, active workflow prompt, or canonical issue state, ignore this guide and follow the authoritative source.

## Coordination Choices

| Situation | Prefer | Notes |
| --- | --- | --- |
| The current step has a clear, verifiable action in the same issue | Same-issue task execution | Keep the edit scope inside the active workflow step. |
| Work has its own objective, outputs, completion checks, and at least one separate-tracking reason | Child issue | Examples include an independent deliverable, evidence bundle, review or integration boundary, materially different responsibility area, or likely multiple AI cycles. Do not invent child schema rules here. |
| A required process is missing or the current workflow cannot express the needed sequence | Workflow template authoring child issue | Create or recommend a workflow template authoring task before doing product work that depends on it. |
| Repo/tool/domain capability is missing outside declared `requires.skills` or `requires.mcp` setup | Skill- or MCP-resolution child issue only when blocking and reusable | See capability gap notes below. |
| A repository, tracker setup, labels, credentials, or service registration is missing | Bootstrap or setup child issue | Record the exact missing setup. Follow configured approval behavior. |
| One task must finish before another can safely run | Dependency | Model ordering with tracker dependencies instead of prose-only reminders. |
| The next safe action depends on product, legal, budget, credential, production, or ambiguous human judgment | Human handoff | Ask the smallest concrete question. Do not continue by guessing. |
| A run revealed reusable process drift, repeated confusion, or weak workflow/skill guidance | Retrospective child workflow or improvement issue | Prefer creating a tracked improvement over silently editing broad process files. |

Capability gap notes:

- Use `alpaca capability list` and `alpaca capability search <gap request>` to compare skill and MCP options by purpose fit, target narrowness, source trust, and quality signals before choosing a resolution path.
- Prefer `alpaca skill create --prompt <gap request>` when a usable skill is the best fit or ties with MCP for the same need.
- Use `alpaca mcp create --prompt <gap request>` when MCP is the better fit or live external service/API/resource/tool access or configured server/tool calls are the core missing capability.
- If declared requirements are unavailable, let AlpacaLoop's required skill/MCP setup issue or human handoff handle it instead of creating a separate resolution child.

## Chat-Driven Issue Creation

When operating through the Alpaca skill in chat, issue creation is user-initiated. Run `alpaca issue create` directly only when the user clearly asks to create, file, or record work as an issue or ticket now.

If the user only asks a question, requests investigation or implementation, mentions a TODO, or notes possible future work, continue in chat. If tracking would help, say that it can be turned into an issue, but do not invoke `issue create`.

Use `--save-draft` only when the user asks to review first or approval is unclear. A saved draft preview is not publication; show the preview and wait for clear approval before creating from the reviewed draft JSON. This chat rule does not replace active workflow child issue, follow-up, dependency, or handoff rules; use the workflow contract when already running inside a managed issue.

For command selection and draft/apply execution details, read [command-flows.md](command-flows.md).

## Abstract Goal Intake

For a broad goal, the first parent issue should usually:

- Establish the goal contract: primary intent, audience or consumer, deliverable or target state, quality bar, observable success evidence, constraints, unknowns, shared readiness, integration responsibility, and next runnable frontier.
- For improvement or optimization goals, establish the evaluation contract before action work: baseline or current state to inspect, metric or evaluation axis, source of truth, measurement window, target or decision threshold, guardrails or non-goals, and claim boundary.
- Inventory missing workflow, skill, repository, data, notification, and monitoring capability.
- Create the next runnable frontier as same-issue tasks or child issues with dependencies, using child issues for independently tracked parent-blocking deliverables, evidence bundles, or review boundaries.
- Leave later work coarse until it reaches the runnable frontier.
- Keep the parent open while unresolved child work, recurring monitoring, or goal validation remains.
- When a child issue starts and its objective is still broad, repeat this intake at the child level. Grandchild issues are normal when they emerge from fresh child-level evidence; they should not be pre-planned by the top parent.

## Learning Capture

At the end of a meaningful issue or workflow branch, consider whether the process learned something durable.

Capture learning when:

- The same ambiguity appeared more than once.
- A workflow step caused unnecessary handoff or rework.
- A repo-local skill was missing a reusable operating rule.
- Verification exposed a recurring gap in setup, monitoring, or release readiness.

Do not capture learning when:

- The issue was a one-off requirement.
- The improvement would encode an unapproved product or policy decision.
- The proposed change would conflict with existing prompt or workflow contract rules.

When learning should be captured, prefer a focused child workflow or improvement issue with a narrow target path, such as one workflow template, one skill file, or one reference section.

## Keep References Lightweight

Use reference files for durable judgment tables, examples, and project operating notes. Use workflow templates for required execution sequence. Use `SKILL.md` for short trigger instructions and where to find deeper references.

## Related Docs

- `alpaca docs show issues`
- `alpaca docs show workflow-templates`
- `alpaca docs show capabilities`
- `alpaca docs show maintenance`
