explain-why
Explain code rationale from git, PRs, issues, and connected MCP sources with citations. Use for design rationale, regressions, and postmortems; use explain-how for current behavior or droid search for session history.
Cynnamoroll · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Cynnamoroll/factory-stack --skill explain-whyAbout this skill
name: explain-why description: "Explain code rationale from git, PRs, issues, and connected MCP sources with citations. Use for design rationale, regressions, and postmortems; use explain-how for current behavior or droid search for session history." license: MIT compatibility: droid
Explain why
Trace reasons through incomplete commits, PRs, tickets, docs, chat, and incident data. Separate records from inference. Read references/epistemics.md before answering.
1. Pin the target and the question
Name the code, pattern, or decision and the question (rationale, tradeoff, edge case, external constraint, dead code, or history sweep). If vague, state your best reading and continue.
2. Build the code anchor yourself
Before any fan-out, collect the seed every investigator gets:
- file paths, line ranges, and key symbols
git blame -L <start>,<end> <file>for last-touch commitsgit log --follow --oneline -- <file>andgit log -1 --format=%B <sha>for history and PR numbersgh pr view <n> --json title,body,author,mergedAt,closingIssuesReferences,comments,reviewsfor each substantive PR- ticket IDs mentioned in commits or PR bodies
3. Fan out one investigator per evidence source
List the MCP servers this session has. Map each to one category: issue tracker, long-form docs, team chat, observability, error tracking, or analytics warehouse. Source control (git, gh) is always a category.
Issue one Task per category, all in one message. Each owns exactly one source and never chases another source's leads. Use a worker Task and state in the prompt that it must not write files or change external state. explorer is read-only but may not carry shell or MCP tools, which these investigators need. Build each prompt from references/investigator-prompt.md. If the target looks defensive (retries, timeouts, null guards, rate limits, feature flags), tell the investigator to search for the incident behind it.
Skip a category only with a written reason that goes in the answer: no MCP server for it, or the source is provably irrelevant (for example, error tracking for a build-time script).
4. Synthesize
Weigh reports, merge duplicate citations, expose contradictions, check doubtful citations, and assign every claim a confidence tier. Follow references/answer-format.md.
If the question precedes a change, end with a constraint set for the change: what to preserve, what to change, what to avoid, and the risk.
Done when
- Every Direct or Supported claim has a citation (PR, ticket, URL, commit, or
file:line). - Inferred and speculative claims are hedged and show their chain.
- "What we don't know" names specific searches that came back empty.
- Sources consulted has one line per category, including skipped ones with the reason.
- No file or external state was changed.