---
title: Issues and Triage
description: Managed issue creation, inspection, approvals, follow-ups, broadcast comments, local logs, AI disable/enable, and unlocks.
relatedCommands:
  - alpaca issue create --help
  - alpaca issue list --help
  - alpaca issue show --help
  - alpaca issue approve --help
  - alpaca issue start --help
  - alpaca issue followup --help
  - alpaca issue broadcast --help
  - alpaca issue disable --help
  - alpaca issue enable --help
  - alpaca issue log --help
  - alpaca issue unlock --help
relatedDocs:
  - quick-start
  - scheduling
  - follow-up
  - workflow-state
  - workflow-options
  - hierarchical-workflows
  - command-flows
  - service-runtime
---

# Issues and Triage

Use this guide when creating AlpacaLoop-managed issues, inspecting queue state, approving foreign input, publishing follow-up work, posting a shared message, reading local run logs, pausing or re-enabling AI processing, or releasing a stuck AI ownership label.

Use `alpaca docs show scheduling` for delayed and recurring work. Use `alpaca docs show follow-up` for independent post-completion work.

## When to Use

- Use `alpaca issue create` only when the user explicitly asks to create, file, record, or publish an issue or ticket.
- Use `alpaca issue list` and `alpaca issue show` for queue inspection and status questions.
- Use `alpaca issue approve` when the current issue assignee wants to approve non-assignee input from the CLI.
- Use `alpaca issue start` when the current issue assignee wants to accept a waiting start approval plan from the CLI.
- Use `alpaca issue followup` when an existing issue should produce a new follow-up issue.
- Use `alpaca issue broadcast` when the same tracker comment must be posted to selected open issues.
- Use `alpaca issue disable` when open issues should stop automatic AI processing without changing their current workflow status.
- Use `alpaca issue enable` when open issues should remove the disabled rule without approving, starting, unlocking, or moving them to `AI: Ready`.
- Use `alpaca issue log` when local worker logs are needed for an issue.
- Use `alpaca issue unlock` when an issue should be returned from `AI: Running` to `AI: Ready` after ownership can be released.

## Key Commands

```bash
alpaca issue create -h
alpaca issue list -h
alpaca issue show -h
alpaca issue approve -h
alpaca issue start -h
alpaca issue followup -h
alpaca issue broadcast -h
alpaca issue disable -h
alpaca issue enable -h
alpaca issue search -h
alpaca issue log -h
alpaca issue unlock -h
```

## Core Behavior

`alpaca issue create --prompt <text>` asks the configured worker to draft issue content from a natural-language request, then runs setup for explicit selector, schedule, worker, follow-up, and autofill options. Explicit template and `no_template` workflow selections skip `workflow_select`; `no_template` uses the built-in default workflow for the target. Unresolved `auto` and `auto_select` workflow selections are saved for later workflow setup after the issue exists. For abstract requests, prompt mode treats the primary outcome as a working hypothesis and uses 5W1H as an internal coverage check so the drafted issue can state the expected outcome, success evidence, constraints, and unknowns without forcing fixed headings. For abstract improvement or optimization requests, prompt mode also preserves evaluation-contract inputs such as the improvement target, baseline to inspect, metric or evaluation axis, source of truth, measurement window, target or decision threshold, guardrails or non-goals, and unknowns. Prompt mode discovers provider issue templates before drafting. Manual mode uses `--title` with `--body` or `--body-file`.

Prompt-mode issue drafting uses the packaged `worker-common`, `workflow-common`, and `issue-create` system prompts. Use the packaged defaults for normal issue creation. If a repository needs durable wording rules for generated issue bodies, run `alpaca docs show setup` to choose the right system prompt, then `alpaca eject system-prompts` and edit the matching `.alpaca/system-prompts/*.md` file. Do not put one-off issue details in the system prompt; pass them in the issue prompt or body instead.

Provider issue template discovery is automatic in prompt mode. GitHub projects load `.github/ISSUE_TEMPLATE.md` first, then Markdown files under `.github/ISSUE_TEMPLATE/` sorted by file name. Gitea projects load Gitea template paths first and then GitHub-compatible paths. GitLab projects load Markdown files under `.gitlab/issue_templates/`. Empty files, non-Markdown files, and issue form YAML files are ignored. Simple frontmatter fields such as `name`, `about` or `description`, and `title` are passed to the worker as template metadata, while the remaining Markdown body is used as the body shape candidate.

The worker chooses `selectedIssueTemplatePath` only when one discovered template is a clear match; otherwise it may omit the field or set it to null. When a template is selected, the drafted issue body should preserve that template's questions, headings, and order. There is no `issue create` CLI option to force a provider issue template selection. To force exact body text, use manual mode or save a draft, review or edit the saved draft JSON, and publish it with `--apply-draft`. The saved `selectedIssueTemplatePath` is review metadata for the draft; AlpacaLoop publishes the final issue body text rather than re-applying a provider template during issue creation.

`--save-draft` writes a reusable draft JSON under the machine-local draft directory and does not create the issue. After review, publish the same reviewed draft with `alpaca issue create --apply-draft <path|->`. Do not rerun prompt mode for an approved draft, because that can change the reviewed content.

Workflow options on `issue create` match the first-line `/alpaca ...` issue comment syntax. They can set workflow selectors, scheduling, recurrence, worker choice, base branch, PR review behavior, AI run limits, start approval, and missing requirement setup behavior. Use `alpaca docs show workflow-options` for the option groups and `alpaca docs show scheduling` for schedule-specific behavior.

`alpaca issue list` is for broad queue triage. Add `--limit <n>` when a compact now/history snapshot is enough, especially before planning or when checking recent closed work. Add `--me` when the user asks about work assigned to the authenticated tracker user, or repeat `--assignee <login>` when the question is scoped to specific assignees. `alpaca issue show` is for one issue's details, labels, comments, canonical workflow state, PR details, and related issues; use `--view followup` when planning follow-up work from a completed source, and prefer bounded related history such as `--children 1 --limit 5` before using `--children all --limit all`. Use `alpaca issue search --title "<keyword>" --state all --limit 10` only when compact list/show output does not identify the relevant issue; use `--query` only when broader provider-backed text search is worth the extra noise.

`alpaca issue approve --issue <id>` posts `/alpaca approve` to the issue after confirming that the authenticated tracker user is the issue's single assignee. The command does not directly update workflow state; normal service scanning records the approval from the posted comment.

`alpaca issue start --issue <id>` posts `/alpaca start` to the issue after confirming that the authenticated tracker user is the issue's single assignee and the issue is waiting for start approval. The command does not directly update workflow state; normal service scanning records the start approval from the posted comment.

`alpaca issue followup --issue <id>` creates a new independent post-completion follow-up issue from an existing issue. Add `--prompt <text>` to store the follow-up request in the created issue body; timing or cadence in that text can be picked up by normal setup/autofill. Use `--dry-run` to preview without creating it. For automatic follow-up judgment, tracker-label requests, and closed-item behavior, run `alpaca docs show follow-up`.

`alpaca issue broadcast` posts one shared comment to explicit issue IDs or to open queue issues selected by status and label. Use `--dry-run` before posting broadly.

`alpaca issue disable --issue <id[,id...]>` adds the `AI: Disabled` rule to open issues while preserving their current workflow status, such as `AI: Ready`, `AI: Running`, or `AI: Needs Human`.

`alpaca issue enable --issue <id[,id...]>` removes only the `AI: Disabled` rule from open issues. It does not approve foreign input, accept start approval, unlock `AI: Running`, or move waiting work to `AI: Ready`.

`alpaca issue log list`, `show`, and `search` inspect machine-local run logs. Local logs are diagnostic material; tracker comments and canonical workflow state remain the shared coordination source.

`alpaca issue unlock --issue <id[,id...]>` requests release of `AI: Running` ownership and returns the issue to `AI: Ready`. The next worker starts after the current worker stops or ownership expires.

Related issue paths have different meanings. Follow-up issues are independent post-completion work. Recurring children are schedule-created work from a recurring parent. Unplanned children and controller children are blocking child issues with their own objective. `missing-workflow-template`, `workflow-template-fit`, required skill, and required MCP setup issues are blockers created before parent planning or execution continues when configured approval behavior allows it. Use `alpaca docs show hierarchical-workflows` for child issue relationships.

Worker continuation choices should match ownership. Same-issue replan keeps work on the source issue when the current plan cannot satisfy the issue-level success criteria. Spawned child issues are for blockers with their own objective and checks. Human handoff is for preferences, product or operational judgment, credentials, approvals, unsafe or irreversible operations, or unavailable information after accessible evidence has been inspected.

## Watch Outs

- Issue creation is intentionally conservative in chat. If the user only asks a question or asks for implementation in the current workspace, do not create an issue unless they ask.
- Managed labels define queue state. If `AI: Ready` and `AI: Needs Human` both exist, AlpacaLoop treats the issue as runnable and prioritizes `AI: Ready`.
- Use workflow templates and required capability docs before declaring `requires.skills` or `requires.mcp`.

## Related Docs

- `alpaca docs show workflow-state`
- `alpaca docs show scheduling`
- `alpaca docs show follow-up`
- `alpaca docs show workflow-options`
- `alpaca docs show hierarchical-workflows`
- `alpaca docs show command-flows`
- `alpaca docs show service-runtime`
