do-investigation-issue

name	do-investigation-issue
description	Use when posting a GitHub investigation issue for an unverified finding, potential gap, or anomaly that needs root-cause analysis before any action is taken. Also use when an audit skill surfaces something suspicious, research reveals a possible gap in the current implementation, or an observed behavior is unexpected but unconfirmed. Issues are labeled 'investigation' only — never 'bug' unless the defect is already confirmed.
allowed-tools	Bash, Read
argument-hint	<component> — <brief finding>

Post Investigation Issue

Creates a GitHub issue that captures an unverified finding and hands it off to a future investigator with enough context to start immediately. The issue does NOT require a confirmed defect — it exists to trigger investigation.

Label Policy

• Always add: investigation
• Never add: bug, feature, or any other label unless the finding already confirms it
• bug is added later by the investigator if root-cause analysis confirms a defect

Title Format

Reliability risk: {component} — {brief one-line description}

Use Reliability risk: for session/agent reliability findings. Use Integration failure: for observed (not hypothetical) integration outages. Use Gap: for missing capabilities surfaced by research or audits.

The component is the system area (e.g., worker, nudge loop, session executor, bridge).

Body Template

Load TEMPLATE.md as the body skeleton. Fill every section — leave no section empty or as a placeholder. If a section genuinely has no content, write one sentence explaining why (e.g., "None — proactive investigation, no remediation attempted yet.").

Quick Start

Step 1: Collect the finding

Identify:

• Component — which part of the system is affected
• Symptoms — what was observed or what the research describes
• Evidence — raw output, error strings, quotes from source material, or code references
• Impact — what breaks or degrades if this is a real defect
• Next steps — concrete checklist of files to check or experiments to run

Step 2: Write the issue body to a temp file

cat > /tmp/investigation_body.md << 'BODY'
## Investigation Finding

**Component:** {component}
**Detected:** {date} ({source — e.g., "amux.io research", "daily-integration-audit", "observed in production"})
**Status:** {Unverified / Observed-once / Persistent}

## Symptoms
{What was observed or what the research describes. Be specific — include error strings, log lines, or quotes verbatim.}

## Diagnostic Output

{Raw evidence: log output, error messages, code excerpts, or external source quotes}

## Steps Attempted
{What remediation was tried, if any. "None — proactive investigation." is a valid answer.}

## Impact
{What functionality breaks or degrades if this is a real defect. Who is affected.}

## Next Steps
- [ ] {Specific file or function to inspect}
- [ ] {Specific experiment or test to run}
- [ ] {Specific behavior to confirm or rule out}
BODY

Step 3: Create the issue

gh issue create \
  --title "Reliability risk: {component} — {brief description}" \
  --body "$(cat /tmp/investigation_body.md)" \
  --label "investigation"

Step 4: Report

Investigation issue created: #{number} — {title}
URL: {url}

When to Err on the Side of Filing

File an issue if you are unsure whether to file. The cost of an unnecessary investigation issue is low. The cost of a missed reliability gap is high. Let the investigator decide what's worth acting on.

File for:

• Any finding from external research (blog posts, post-mortems, docs) that may apply to this codebase
• Any audit result that surfaces a suspicious gap, even if unconfirmed
• Any observed anomaly that occurred once and wasn't diagnosed
• Any pattern the current watchdog or monitoring might miss

Do not file for:

• Things already tracked in an open issue (search first: gh issue list --search "KEYWORDS")
• Things that have been explicitly ruled out by prior investigation
• Aspirational features with no evidence of a current gap

Cross-Repo Usage

The gh CLI uses the current working directory's git remote by default. No --repo flag needed when invoked from within the target repo. If invoked from outside a repo, pass --repo owner/name explicitly.