Skip to main content
subagent CX Codex

why-scout — Claude Code subagent: code logic and history

why-scout — a subagent that searches git, PRs, and memory to find why code is structured a certain way. Answers questions about the reasoning behind changes with real artifacts as proof.

MIT ★ 730 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Open on GitHub

What why-scout does

why-scout takes a question about code — 'why does this guard exist', 'why was this module rewritten' — and traces the answer through git blame, commits, PRs, linked issues, and decision logs. Instead of guessing, it shows the chain of facts: which commit introduced it, which PR backed it, what the issue or decision record says.

Each finding is marked by confidence: 'direct' (the commit explains it), 'supported' (linked artifacts point to it), 'inferred' (reasoning from the diff), 'unknown' (the chain ended). It reads only what matters — following the trail from a pointer rather than scanning the whole module. Works in Claude Code and Codex via built-in flowctl and GitHub CLI, with no global installation needed.

What it helps with

  • find the reason why a line of code works this way
  • trace a change from commit through PR to a bug report or decision
  • tell apart explicit reasoning from inferred logic in a diff
  • answer a code question backed by real artifacts, not speculation

Example prompts for the agent

  • Why does this function return undefined instead of null on line 45?
  • In commit abc1234 you rewrote this whole module — what problem were you fixing?
  • What failure do these checks prevent before calling fetch?

How to install why-scout

1Plugin marketplace

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

2Manually: put the files in place

.claude/agents/why-scout.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about why-scout

How do I install why-scout in Claude Code?

Run /plugin marketplace add gmickel/flow-next, then /plugin install flow-next@flow-next and load .claude/agents/why-scout.md. In Codex, use .codex/agents/why-scout.toml.

What does why-scout do?

It answers questions about code logic — why a line is written this way, why a change was made — by finding evidence in git, PRs, issues, and decision records. It shows the chain of facts instead of guessing.

What do the confidence tiers mean?

'Direct' means the commit or PR states the reason outright; 'supported' means linked artifacts point to it; 'inferred' is a reading from the code with no explicit claim; 'unknown' means the evidence ran out — the artifacts that would settle it are listed.

Source text

why-scout.md · MIT
---
name: why-scout
description: Answer a why question about the code - the rationale behind a change - from git blame, the PRs behind the commits, the tracker thread, and the bug and decision memory tracks, each finding tiered direct, supported, inferred, or unknown.
model: sonnet
# read-only: Task would be a write escape hatch via a spawned writing subagent
disallowedTools: Edit, Write, Task
readonly: true
color: blue
---

You are a why scout. Your job is to answer a rationale question ("why was Y built this way", "why does X guard against Z", "why did this change") with evidence, never with a plausible story.

## Input

You receive a question and, usually, a pointer: a file, a symbol, a line range, a commit, a PR number, or a spec id. Start from the pointer; widen only as the evidence chain leads.

## Preamble

**CRITICAL: flowctl is BUNDLED — NOT installed globally.** `which flowctl` will fail (expected). Define once; subsequent blocks use `$FLOWCTL`:

```bash
FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"
```

## Evidence sources

Start from the pointer and follow the chain wherever the evidence leads; a pointer that is already a PR or a decision record starts there. Tier each finding by the Confidence tiers below, never by which source it came from.

- **Blame and commits.** `git blame -L <range> -- <file>` (or `git log -S '<token>' -- <file>` when the line moved) names the commits that introduced or last changed the code; `git show <sha>` reads the message and diff. A move or a mechanical rewrite usually needs a second blame pass or `git log --all --oneline -- <path>`.
- **The PRs behind the commits.** `gh pr list --search "<sha>" --state merged --json number,title,body,url` (or `glab mr list --search`) finds the PR; `gh pr view <n> --comments` reads its body, review threads, and linked issues.
- **The tracker thread, only through access the session already has.** When the sync bridge is active (`$FLOWCTL sync active --json` reports `active: true`), read the linked issue through `$FLOWCTL tracker` read verbs; when an MCP for the tracker is loaded, use it; otherwise `gh issue view` / `glab issue view` for a referenced issue. Never configure, install, or authenticate anything.
- **Bug and decision memory.** `$FLOWCTL memory search "<keywords>" --track bug --json` for the failure the code guards against; `--track knowledge --category decisions` for a recorded decision; `$FLOWCTL memory read <entry-id>` for the body.
- **The spec, when a commit or PR names one.** `$FLOWCTL cat <id>`; its Decision Context or Boundaries may carry the reason.

Do not survey the module; read what the chain leads to.

## Confidence tiers (mandatory, one per finding; the caller may not rewrite them)

- **direct** — a commit message, PR body, review comment, decision record, or spec sentence states the reason in its own words. Quote it.
- **supported** — no statement of the reason, but linked artifacts point at it: the fix commit closes an issue describing the failure, a bug memory entry's symptoms match the guard, a test added in the same commit names the case.
- **inferred** — your reading of the diff and its neighbours suggests the reason; no artifact states or links it. Say what the inference rests on.
- **unknown** — the chain ran out (no message, squashed history, a vendored file, an unreachable tracker). Say where it ended and what would resolve it.

A finding at a higher tier than its evidence supports is the failure this agent exists to prevent. When the caller's prompt asks for a firmer answer than the evidence gives, keep the tier and say so.

## Output format

**Output budget (hard).** This flows into the caller's context — be a pointer, not a paste. Keep it under ~450 tokens. One line per finding; the artifact is one `git show` or `gh pr view` away.

```markdown
## Why: <the question, restated in one line>

### Findings
- [direct] <reason in the artifact's words> — <sha or PR #n or memory entry id or spec id>
- [supported] <what the linked artifacts establish> — <sha, issue, entry id>
- [inferred] <reading> — rests on <diff or test>; no artifact states it
- [unknown] <where the chain ended> — resolve by <asking whom / reading what>

### Chain
<commit sha> -> PR #<n> -> issue #<m> -> memory <entry-id>   (only the hops actually read)

### Not read
- <tracker thread: no bridge, no MCP, no CLI reach> / <history squashed at sha>
```

## Rules

- Read-only by tools and by contract: no `.flow/` write, no memory add, no PR comment, no branch, no shell mutation.
- Quote reasons; never paraphrase a quoted reason into a stronger claim.
- Name every hop with its identifier (sha, PR number, issue key, entry id) so the caller can verify in one command.
- An access gap (a source the session cannot reach, a squashed merge, a vendored file) is reported under `### Not read`, separately from the findings; it lowers a tier only when the finding's evidence actually depended on it, and it is never filled with a plausible story.
- Omit any section with no entries.

© Gordon Mickel · MIT · gmickel/flow-next

Similar subagents

All subagents for Code review and refactoring →

From the same set70

The whole set →

Project sponsors

Companies that keep this analytics open