openspec-beads-followup

name	openspec-beads-followup
description	Triage discovered work into in-scope bug, in-scope task, or out-of-scope follow-up. Sets correct type, priority, and dependency linkage in Beads. Does not silently expand the claimed issue's scope.
license	MIT
compatibility	Requires bd (beads) CLI.
metadata	{"author":"openspec","version":"1.0","generatedBy":"1.1.1"}

Triage work discovered during implementation without expanding the scope of the claimed issue.

Source-of-truth rule: OpenSpec owns agreed scope. Do not expand a claimed Beads issue to cover discovered work. File a new issue instead.

Input: A description of the discovered work and the current claimed issue ID.

Decision tree

Answer these questions in order:

Q1: Does this change public API shape, user-visible behavior, acceptance criteria, or data model?

• Yes → This is a scope change. Stop here. Use the openspec-beads-scope-change skill instead. Do not file a Beads issue until OpenSpec is updated.
• No → Continue to Q2.

Q2: Is this a defect in behavior the OpenSpec change already specifies?

• Yes → In-scope bug. See below.
• No → Continue to Q3.

Q3: Is this work required for the current OpenSpec change to ship correctly?

• Yes → In-scope task (priority=2). See below.
• No → Out-of-scope follow-up (priority=4). See below.

---

In-scope bug

bd create \
  --title="<concise bug description>" \
  --description="Bug found while implementing openspec/changes/<change-id>. Existing scope already requires <correct behavior>. <Steps to reproduce or evidence>. Add regression test coverage." \
  --type=bug \
  --priority=1

Link it as a blocker if the current issue cannot be closed without it:

bd dep add <current-issue-id> <new-bug-id>

In-scope task

bd create \
  --title="<task description>" \
  --description="Discovered while implementing openspec/changes/<change-id>. Required for this change to satisfy acceptance criteria. <Context and expected behavior>." \
  --type=task \
  --priority=2

Link downstream work that depends on it:

bd dep add <downstream-issue-id> <new-task-id>

Out-of-scope follow-up

bd create \
  --title="<follow-up description>" \
  --description="Follow-up idea discovered during openspec/changes/<change-id>. Not required for the current change. Consider after it ships. <Context and motivation>." \
  --type=task \
  --priority=4

No dependency linking needed for pure follow-ups.

---

After creating the issue

Tag with the standard context labels (MANDATORY). Every Beads issue must carry branch:<name>, worktree:<name>, repo:<name>, plus openspec:<change-id>:

source ~/.claude/ruflo/lib/tags.sh
PREFIX=$(ruflo_key_prefix)
BRANCH_LABEL=$(echo "$PREFIX"   | awk -F'|' '{print $1}')
WORKTREE_LABEL=$(echo "$PREFIX" | awk -F'|' '{print $2}')
REPO_LABEL=$(echo "$PREFIX"     | awk -F'|' '{print $3}')

bd tag <new-issue-id> "$BRANCH_LABEL"
bd tag <new-issue-id> "$WORKTREE_LABEL"
bd tag <new-issue-id> "$REPO_LABEL"
bd tag <new-issue-id> "openspec:<change-id>"

Verify with bd show <new-issue-id> — the LABELS line must show all four.

Report:

• Issue type (bug / in-scope task / follow-up)
• New Beads issue ID and priority
• Whether it blocks the current issue or not

Write triage rationale to memory (run only if ruflo is installed):

source ~/.claude/ruflo/lib/tags.sh 2>/dev/null && \
  KEY="$(ruflo_key_prefix)|openspec:<change-id>|issue:<new-issue-id>|type:followup-triage|ts:$(date +%s)" && \
  ruflo memory store -k "$KEY" -v "Triage: <bug|in-scope-task|follow-up>. Reason: <why this classification>. Parent issue: <current-issue-id>." 2>/dev/null || true

Then:

bd ready

Guardrails

• NEVER expand the scope of the currently claimed issue — file a new issue for any discovered work
• NEVER silently defer discovered work — always file a Beads issue
• NEVER skip the context tagging step — branch:<name>, worktree:<name>, repo:<name> labels are required on every issue so future sessions can filter cleanly
• If in doubt between Q2 and Q3, file as bug at priority=1 and let the user adjust
• If Q1 is yes, stop and use openspec-beads-scope-change — OpenSpec must be updated before filing in Beads