olibyte/jev-trader / .agents/skills/why
why
VerifiedUse for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.2 KB |
| references/epistemics.md | markdown | 6.6 KB |
| references/investigator-prompt.md | markdown | 5.4 KB |
| references/source-playbook.md | markdown | 1.3 KB |
| references/sources/code-archaeology.md | markdown | 3.3 KB |
| references/sources/databricks.md | markdown | 6.8 KB |
| references/sources/datadog.md | markdown | 4.9 KB |
| references/sources/incident-postmortem.md | markdown | 1.9 KB |
| references/sources/linear.md | markdown | 2.9 KB |
| references/sources/notion.md | markdown | 2.8 KB |
| references/sources/sentry.md | markdown | 4.6 KB |
| references/sources/slack.md | markdown | 3.0 KB |
| references/synthesizer-prompt.md | markdown | 7.0 KB |
references/synthesizer-prompt.md
View on GitHub# Synthesizer Prompt Template
Fill in the placeholders.
---
You are answering a "why" question about a piece of code by synthesizing findings from investigators who searched different historical sources (source control, issue / ticket tracker, long-form documents, real-time team chat, infrastructure observability, error / exception tracking, product analytics warehouse, and code comments). Produce a confidence-weighted, evidence-cited narrative that says honestly what the evidence supports, and just as honestly what it doesn't.
## The Question
> {QUESTION}
## The Code Anchor
**Target files:** {FILES_WITH_LINE_RANGES}
**Key symbols:** {SYMBOLS}
## Investigator Findings
{ALL_INVESTIGATOR_FINDINGS}
## Sources That Weren't Searched
{SKIPPED_SOURCES_WITH_REASONS}
## Epistemics Framework
You MUST follow `references/epistemics.md`. Read it in full before writing. The key rules:
1. Every claim must sit in one tier: **Direct**, **Supported**, **Inferred**, **Speculative**, **Unknown**. The tier sets its section and its phrasing.
2. Every Direct/Supported claim must have a citation (PR #, ticket ID, doc URL, chat permalink, commit hash, or file:line).
3. Inferred and Speculative claims must use hedged language ("appears to", "likely", "suggests", "one possibility is").
4. Never cite code as evidence for its own intent.
5. Document gaps. Don't fill them with plausible-sounding guesses.
6. Treat a hypothesis embedded in the user's question as a candidate, not a conclusion. Check it independently.
## Instructions
1. **Read all investigator findings** and weigh the evidence yourself. Investigators gathered raw evidence, not conclusions.
2. **Merge overlaps.** When several investigators cite the same PR, ticket, or doc, give it one authoritative reference.
3. **Surface contradictions.** When two items disagree, show both. Don't pick one.
4. **Calibrate each claim.** Find its evidence and tier. Direct: cite it and state it plainly. Inferred: hedge it and show the inference. Speculative: mark it. No evidence: put it in the gaps.
5. **Verify citations by spot-checking.** If you're uncertain a cited item exists or says what the investigator claims, check it by reading the codebase or calling MCP tools. Don't propagate errors. Do not write files, commit, or modify external state.
6. **Don't overreach.** The user will act on this. Leave an open question open rather than fill it with a confident guess.
## Output Format
Write for the user, in this exact structure:
---
### The Question
Restate the user's question in one or two sentences.
### The Code in Question
File paths, line ranges, key symbols. Two or three lines to orient a cold reader.
### What We Found
Claims with textual evidence, each quoted or paraphrased and cited precisely:
- **[Direct]** {Claim}. Source: [PR #123](url) / ticket ID / file:line. {Brief quote or paraphrase.}
- **[Supported]** {Claim}. Evidence: {list of items and what each contributes}.
`[Direct]` is single-source, explicit evidence. `[Supported]` is multiple indirect items converging on a conclusion.
### What We Can Reasonably Infer
Claims stated nowhere but well-supported by indirect evidence. Each bullet must make the inference chain visible ("Given A and B, it's likely that C") and must use hedged language ("appears to", "likely", "suggests", "is consistent with"):
- **[Inferred]** {Hedged claim}. Reasoning: {the specific evidence and the inference step}.
Skip this section if there's nothing to infer.
### Competing Hypotheses
If the evidence fits multiple stories, present each. Don't force a winner the record doesn't support. For each hypothesis:
- **Hypothesis:** {one-sentence statement}
- **Evidence for:** {specific items}
- **Evidence against or missing:** {what would need to be true but isn't, or what counter-signals exist}
Skip this section if there's a single clear answer.
### What We Don't Know
Specific gaps: "We searched the issue tracker for [query1], [query2], [query3] and found no issue discussing the rate-limit threshold", not "We don't know why." Include:
- Questions that went unanswered
- Searches that returned nothing
- Sources that were unavailable, and why (such as a missing real-time team chat MCP)
- People who would likely know but whom you can't ask
### Sources Consulted
What was actually searched, so the user can judge coverage and redirect:
- **Source control history**: {file paths}, {number of commits reviewed}, PRs #{numbers}, and code comments searched. Or "Not searched. This should not happen because git and `gh` are always expected."
- **Issue / ticket tracker**: {ticket IDs and keyword searches}. Or "Not searched. No matching MCP available in this environment."
- **Long-form documents**: {page titles and search queries}. Or "Not searched. No matching MCP available in this environment."
- **Real-time team chat**: {channels searched, date ranges, queries}. Or "Not searched. No matching MCP available in this environment."
- **Infrastructure observability**: {dashboards, monitors, metrics, logs, traces, or incidents searched}. Or "Not searched. No matching MCP available in this environment."
- **Error / exception tracking**: {issues, events, or releases searched}. Or "Not searched. No matching MCP available in this environment."
- **Product analytics warehouse**: {fully-qualified tables queried, the time windows, and the numeric summaries (counts, percentiles, first/last-seen timestamps) that bore on the question}. Or "Not searched. No matching MCP available in this environment."
### Confidence Summary
One or two sentences on overall confidence, e.g.:
> "The core rationale (A) is well-supported by direct PR and ticket evidence. The specific threshold value (100) is inferred from the surrounding context but not explicitly documented. The question of whether this was driven by a customer request could not be answered. No relevant issue tracker or long-form doc content surfaced, and real-time team chat search was unavailable."
---
## Quality Check Before Returning
Revise if any item fails:
1. Does every claim in "What We Found" have a citation? If not, add one or move it to "Inferred" or "Hypotheses."
2. Is the phrasing tier-appropriate? (Direct claims can use "because". Inferred claims cannot.)
3. Did you surface every contradiction you noticed, or quietly pick one?
4. Does "What We Don't Know" name specific gaps? If it's empty or missing, be suspicious. Historical investigations almost always have gaps.
5. Did you check any hypothesis embedded in the question against the evidence rather than rubber-stamp it?
6. Did you cite code as evidence for its own intent? Remove it. Code is mechanics, not motivation.
7. Is the tone calibrated? A confident-sounding answer on weak evidence is the exact failure this skill exists to prevent.
The value of this output is its honesty, not its authority. A reader who takes it to the original author, an engineering lead, or a product manager should know what's known, what's inferred, and what's missing, so they can ask the right follow-up questions. Optimize for being useful, not for looking decisive.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |