Investigate

Investigate

Invocation: user only.

Iron law

No fix proposals without root-cause investigation first.

Jumping to a fix on symptoms creates whack-a-mole problems — the same thing recurs in a new form. Find the root cause, then act. If you can't find the root cause, say so. Don't fabricate one to have something to propose.

What this skill is for

Process and project issues, not just code. The shape is the same either way:

• A project slipped its commitment date
• A recurring blocker keeps surfacing across projects
• A customer is escalating repeatedly and the pattern isn't clear
• A team is missing a ritual (standups, reviews) and nobody can say why
• An incident happened and we need a postmortem, not a blame hunt
• Cross-team dependencies keep breaking at the same seam

If it's a code bug, the methodology still works — but a dedicated engineering investigate skill exists in gstack or similar; use this one when the answer might be organizational, not technical.

Phase 1 — collect symptoms

Before any hypothesis, gather evidence. Ask the user for anything you need, one question at a time, not a batch.

Pull what you can from sources:

• Notion: relevant project page, its history, any linked specs / retros / decisions
• Slack: recent channel activity related to the issue — search for the project/person/customer name in the window where things went wrong
• Gmail / Calendar (if relevant): emails or meetings that mark decision points or external pressure
• Fathom: meeting summaries where the issue came up
• GitHub (if enabled): PRs or issues related to the affected work

Produce a clean symptom statement: "What we observed is X, starting around Y, affecting Z." Confirm with the user before moving on.

Phase 2 — pattern recognition

Before forming a hypothesis, check if this matches a pattern. Common ones:

• Scope creep — the work's definition moved mid-stream, nobody said so out loud
• Silent dependency — the critical-path blocker was owned by someone who didn't know it was critical
• Unclear owner — two people thought the other was driving
• Missing decision — everyone's waiting on a call nobody made
• Context collapse — a teammate who held the context left, was OOO, or reassigned
• Fake agreement — the team nominally agreed in a meeting but the written record shows divergent interpretations
• Recurring hotspot — this exact issue happened before in the same area. Check prior retros / investigate reports.

Search prior investigation reports and retros in Notion for the same area. Recurring issues in the same place are an organizational smell, not coincidence.

Phase 3 — hypothesis testing

State a specific, testable root-cause hypothesis. Example:

• Good: "The spec handoff from PM to eng on March 20 didn't include the rate-limit requirement that QA flagged in their April 3 message; eng built to the spec; QA found the gap on April 10."
• Bad: "There was a communication gap." (Not testable, not specific.)

Verify the hypothesis. Ways to verify without taking action:

• Check artifacts against each other (spec vs. actual PR vs. QA ticket)
• Ask the people involved one at a time — not a group thread that turns into a defense session
• Look for disconfirming evidence. If the hypothesis is "unclear owner", find the moment ownership was clarified (or should have been) and look for evidence of that signal being missed

3-strike rule

If 3 hypotheses fail to match evidence, stop. Tell the user:

"Three hypotheses tested against evidence. None match. This may be a structural issue, not a local one."

Offer options:

• Continue with a new, broader hypothesis (state it)
• Escalate to someone with more context (who?)
• Instrument the area — add a check, a status update cadence, a tighter review — and catch it next time

Phase 4 — write the investigation report

Only after a root cause is confirmed — or the 3-strike rule triggered — produce the report.

# Investigation: <one-line title>

**Date:** <today>  ·  **Investigator:** <user>  ·  **Status:** <Root cause found | Unresolved after 3 hypotheses | Ongoing>

## Symptom
<What we observed. Specific. Dated.>

## Timeline
- <YYYY-MM-DD> <event>
- ...
(Aim for 4-8 entries. The moments that mattered, not every Slack message.)

## Root cause
<If found: the specific, testable claim about what was wrong.>
<If unresolved: "Unresolved — three hypotheses tested. See below.">

## Evidence
- <link to artifact, quote, or event that supports the root cause>

## Hypotheses considered (including the one that held)
1. <hypothesis> — <evidence for/against> — <held / rejected / partial>
2. ...
3. ...

## What this is *not*
<Useful when investigating something people have strong opinions about. Explicitly rule out explanations that would be obvious but aren't supported — "this was not a capacity problem, because X.">

## Contributing factors (non-causal)
<Things that made the failure mode more likely or harder to catch, but aren't the root cause. Keeps the report honest without scope-creeping into everything.>

## What to do next
- <specific action, owner, date>
- ...

## Systemic fix (if any)
<If this recurs in the same area, or matches a prior pattern, propose a structural change. Not "communicate better." Specific: "Add a check in the spec-review skill that asks about rate limits." "Make the PgM the DRI on cross-team dependencies by default.">

## Don't blame
<One paragraph. A good investigation names what happened and what to change — not who to criticize. Read the report once and delete anything that reads like an accusation.>

Phase 5 — review and publish

Show the draft. Common edits:

• Tone down / tone up specific sections per the user's read of sensitivity
• Correct timeline entries
• Remove people's names where the structural point can be made without them

On approval:

• Save to Notion under <<NOTION_INVESTIGATIONS_PATH>> (or ask for the destination if unset)
• If the report recommends actions, offer to open follow-ups in the team's tracker
• If the report surfaces a new risk, offer to file it via /role-pgm:risk-log add

Never auto-publish. Never post to Slack unless the user asks — investigation reports are usually shared deliberately, to specific people, not broadcast.

Don't

• Don't propose a "quick fix for now." There is no "for now." Fix the root cause or instrument and wait.
• Don't run a root-cause investigation as a group thread. People defend themselves in group settings. Talk to people one at a time.
• Don't investigate in public channels while the investigation is open. The write-up is the public artifact.
• Don't skip Phase 2 (pattern recognition). A recurring issue in the same area is almost always structural — treating it as new each time is how orgs accumulate debt.
• Don't write a report that reads like a performance review. If a name appears more than twice, re-read and de-personalize wherever possible.