# Starlight Investigate

> Diagnose a reproducible software failure by separating observations from hypotheses, locating the failing boundary, and defining regression evidence. Use when a bug, failed check, production incident, or unexpected behavior needs a root-cause report; modify code only when the user also authorizes a fix.

- Skill: `frankxai/starlight-investigate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add frankxai/starlight-investigate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/frankxai/starlight-investigate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: frankxai (https://skillmd.com/u/frankxai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/frankxai/starlight-investigate

---


# Starlight Investigate

## Purpose

Find the smallest evidence-supported explanation for a failure without speculative edits or unrelated cleanup.

## When it fires

- A test, build, deployment, API, UI flow, or runtime behavior fails.
- The failure is intermittent and needs boundary isolation.
- The user asks for diagnosis, root cause, or incident analysis.

## Inputs

- Expected and observed behavior.
- Reproduction steps, logs, timestamps, environment, and relevant revision.
- Repository instructions and known constraints.

## Workflow

1. Capture the exact failure and determine whether it reproduces.
2. Reduce it to the smallest safe reproduction while preserving the failing condition.
3. Trace inputs, state transitions, and outputs across the suspected boundary.
4. List competing hypotheses and the observation that would falsify each one.
5. Run the cheapest discriminating checks first.
6. State the root cause only when evidence rules out plausible alternatives.
7. If a fix is authorized, apply the smallest causal change and run focused plus regression checks.
8. Record residual uncertainty, monitoring, and rollback needs.

## Output contract

Return:

- `symptom` and reproducibility;
- `evidence` with commands, locations, and relevant revisions;
- `hypotheses_tested` and falsification results;
- `root_cause` or `not_yet_proven`;
- `impact_boundary`;
- `recommended_fix` without implementation when diagnosis-only;
- `verification` and `residual_risk`.

## Tools & MCP

Prefer repository search, focused tests, logs, and read-only platform inspection. Redact credentials and personal data. Do not alter production state to make a diagnosis easier.

## Quality bar

- Observation, inference, and decision are clearly separated.
- “Could be” is not presented as root cause.
- The reproduction and verification are copyable.
- The proposed fix addresses the causal boundary rather than masking the symptom.
- Unrelated working-tree changes remain untouched.

## Example

Input: “The preview works, but the production API returns 415.”

Good output: evidence showing the exact content-type mismatch at the request boundary, alternatives ruled out, a minimal header-validation fix, and focused plus production-preview checks.

---

Built on SIP — Starlight Intelligence Protocol
Vertical: starlight-agent-skills · portable capability layer