roborew/fanout-issues

Fanout issues

When

docs/prd/<slug>.md has valid YAML frontmatter with tickets: (preferred) or legacy slices:, plus parent_issue and target_repos as defined in docs/prd/_template.md.

How

From this repo root, run exactly once per slug (unless resuming after a failed run):

bin/fanout <slug>

bin/fanout (tickets mode) runs fanout-audit, then sync-fanout-bodies, then feature-check --level fanout. If any step fails, stop — do not hand-create issues.

After editing docs/prd/<slug>.md later, run bin/feature-upgrade <slug> (same body sync + broader checks).

Hard rules

• Only bin/fanout <slug> creates child issues — never hand-roll gh issue create for PRD tickets.
• Never run fanout twice in parallel for the same slug (the script holds a lock; a second run exits 8).
• Never fanout in parallel subagents or parallel bash calls.
• If fanout reports Skipping existing #N, that is success — do not create another issue for the same ticket.
• Re-run fanout only when resuming after failure or after fixing the PRD; idempotent skips are expected.
• If duplicate open issues exist for one ticket id, close duplicates before re-running fanout; sync only updates one matched issue per ticket.

When fanout fails or exits non-zero

Do not assume zero issues were created. Partial fanout is common.

1. Run bin/fanout-audit <slug> and read the report (OK / MISSING / DUPLICATE / ORPHAN per ticket).
2. Never run gh issue create for PRD tickets — not even “just the missing ones.”
3. If lock error (exit 8): wait, or remove stale .fanout-lock-<slug>/ only when no fanout process is running, then bin/fanout-audit, then bin/fanout again.
4. If duplicate (exit 10 or audit DUPLICATE): close the extra issues (human or delegated cleanup), re-run audit until PASS, then bin/fanout (creates only MISSING).
5. If audit shows only MISSING: bin/fanout <slug> again — it skips existing matches via existing_issue_number.
6. If fanout keeps failing: debug the script error — do not bypass with manual creates.

Rules

tickets: (preferred)

• Each ticket row becomes one child issue in the repo named by repo (full owner/repo matching docs/agents/repos.md).
• Issues are created in dependency order (depends_on task ids).
• Labels include feature:<slug>, state:ready-for-agent, mode:afk or mode:hitl, and category:feature.
• The issue body embeds fenced opencode-task-json metadata (task id, acceptance, test_commands, commit_message, etc.) plus human-readable sections.

Legacy slices:

• Each slice key must be a full owner/repo string matching docs/agents/repos.md.
• One broad issue per repo (same label set where applicable).

Idempotency

• Before each create, bin/fanout checks existing issues by exact title and embedded task id (opencode-task-json, yaml, or legacy **Task ID:** bodies).
• Duplicate ticket ids or duplicate (repo, title) pairs in the PRD cause fanout to exit 7 before creating anything.
• Multiple GitHub issues matching one ticket cause fanout to exit 10 — close extras first.