git:20260506.19937d7 to git:20260526.82a2442

31 added, 7 removed. Audit A to A.

---

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](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

+ ### Step 2: Draft, Verify, and Create the Issue (single bash invocation)

+ **Single-shell invariant (load-bearing):** The whole sequence below — allocate scratch path, write body, verify anchor, publish, cleanup — MUST run inside ONE bash tool invocation. Each Bash tool call spawns a fresh shell with a new `$$`, so splitting these steps across calls loses `OWNER_PID`/`OWNER_TS`/`ANCHOR`/`DRAFT` and breaks anchor verification. Do not split.

```bash

- cat > /tmp/investigation_body.md << 'BODY'

+ # Per-invocation draft path (mktemp ensures no collision with any concurrent agent).

+ # Anchor header proves the draft we publish is the draft we wrote.

+ # DO NOT "simplify" the anchor check away — it defends against another agent

+ # clobbering the scratch file between write and publish.

+ DRAFT=$(mktemp "${TMPDIR:-/tmp}/investigation_body.XXXXXX") || { echo "ERROR: mktemp failed" >&2; exit 1; }

+ OWNER_PID=$$

+ OWNER_TS=$(date +%s)

+ ANCHOR="draft-owner: pid=${OWNER_PID} ts=${OWNER_TS}"

+ # Write the anchor as the first line via printf (expands ${ANCHOR}),

+ # then append the body with a QUOTED heredoc so the {component}/{date}/etc.

+ # placeholders remain literal for the agent to substitute (no shell expansion).

+ printf '\n' "${ANCHOR}" > "$DRAFT"

+ cat >> "$DRAFT" << '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

+ # Verify the anchor BEFORE publishing. Mismatch = a foreign agent clobbered

+ # the file, or our own write failed — never publish unknown content.

+ if ! head -1 "$DRAFT" | grep -qF ""; then

+ echo "ERROR: draft anchor mismatch — refusing to publish unknown content" >&2

+ echo " expected first line: " >&2

+ echo " actual first line: $(head -1 "$DRAFT")" >&2

+ rm -f "$DRAFT"

+ exit 1

+ fi

- ```bash

gh issue create \

--title "Reliability risk: {component} — {brief description}" \

- --body "$(cat /tmp/investigation_body.md)" \

+ --body "$(cat "$DRAFT")" \

--label "investigation"

+ # Best-effort cleanup; mktemp paths live under $TMPDIR and the OS reaps stragglers.

+ rm -f "$DRAFT"

```

- ### Step 4: Report

+ ### Step 3: 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.