dsh-pstack 0.1.0 → 0.2.0-beta.3

package/dist/assets/skills/typescript-best-practices/references/patterns.md

@@ -1,328 +0,0 @@
-# TypeScript patterns
-
-Code examples for each rule in `SKILL.md`. The underlying principles are language-agnostic. See the **type-system-discipline** and **boundary-discipline** principle skills.
-
-## Branded types
-
-Brand primitives so they can't be mixed up. Validate once at the boundary. Downstream code trusts the type.
-
-```ts
-type AgentId = string & { readonly __brand: "AgentId" };
-
-function isAgentId(input: string): input is AgentId {
-  return isUUID(input);
-}
-
-function parseAgentId(input: string): AgentId {
-  if (!isAgentId(input)) throw new Error(`Invalid agent id: ${input}`);
-  return input;
-}
-
-function focusAgent(id: AgentId): void {
-  /* input is trusted */
-}
-```
-
-Match the `readonly __brand: 'X'` shape. Don't invent a new convention.
-
-## Discriminated unions
-
-Model variants with a literal discriminant. Every variant shares the field name and each variant's value is unique, so impossible combos can't be represented.
-
-```ts
-// Don't. Boolean + optionals lets contradictory states exist.
-type DiffState = { loading: boolean; diff?: GitDiff; error?: string };
-
-// Do. Only valid states exist.
-type DiffState =
-  | { kind: "loading" }
-  | { kind: "ready"; diff: GitDiff }
-  | { kind: "error"; error: string };
-```
-
-Pick one discriminant name (`kind`, `type`, `tag`) and stick to it.
-
-## Constructive modeling
-
-Build the type from parts that are all legal instead of restricting a loose type with runtime checks.
-
-Non-empty, via a variadic tuple:
-
-```ts
-type NonEmpty<T> = [T, ...T[]];
-
-// Don't: T[] plus a length check every caller must repeat
-function pickWinner(entries: string[]): string {
-  if (entries.length === 0) throw new Error("no entries");
-  return entries[Math.floor(Math.random() * entries.length)];
-}
-
-// Do: an empty value of the type can't exist
-function pickWinner(entries: NonEmpty<string>): string {
-  return entries[Math.floor(Math.random() * entries.length)];
-}
-```
-
-Where a plain `T[]` arrives, narrow once with a guard. The fact then travels in the type:
-
-```ts
-const isNonEmpty = <T>(arr: T[]): arr is NonEmpty<T> => arr.length > 0;
-```
-
-Even length, as pairs:
-
-```ts
-type Pairs<T> = [T, T][];
-```
-
-A time range, as start plus duration:
-
-```ts
-// Don't: a comment holds the invariant
-type TimeRange = { start: Date; end: Date }; // start <= end
-
-// Do: a negative range can't be written; derive end when needed
-type TimeRange = { start: Date; durationMs: number };
-```
-
-Keep `durationMs` a plain number. Brand it (per Branded types) only if a raw number could be passed where a duration is expected, not by reflex. Pick the representation that makes the bad state unconstructable, then expose the reading you need on top (`pairs.flat()`, a `rangeEnd()` helper).
-
-## Simplest total type
-
-Don't strengthen everything. Keep `T[]` when every operation on it is total:
-
-```ts
-const sum = (xs: number[]) => xs.reduce((a, b) => a + b, 0); // [] is 0, fine
-```
-
-Strengthen when the loose type forces a lie at a use site. The tells are `!`, `arr[0] as T`, and a "should never happen" throw:
-
-```ts
-// Don't: partiality smuggled past the compiler
-function newestSession(sessions: Session[]): Session {
-  return sessions.at(0)!;
-}
-
-// Do: strengthen the input; the assertion disappears
-function newestSession(sessions: NonEmpty<Session>): Session {
-  return sessions[0];
-}
-```
-
-Weakening the result to `Session | undefined` is the other total signature.
-
-## `unknown` over `any`
-
-External data is always `unknown`. Narrow before use.
-
-```ts
-// Don't
-function handle(input: any) {
-  return input.foo.bar;
-}
-
-// Do
-function handle(input: unknown) {
-  if (typeof input === "object" && input !== null && "foo" in input) {
-    // narrowed; compiler verifies access
-  }
-}
-```
-
-External sources include RPC payloads, `JSON.parse`, `postMessage`, IPC, file contents, environment variables, database results.
-
-## Schemas before hand-rolled guards
-
-Before writing a property-by-property type guard for external data, look for the repository's runtime schema library and existing schemas. Let one schema own validation and derive the TypeScript type from it. Do not maintain a schema, a duplicate interface, and a guard that can drift apart.
-
-```ts
-import { z } from "zod";
-
-const UserSchema = z.object({
-  id: z.string().uuid(),
-  role: z.enum(["admin", "member"]),
-});
-
-type User = z.infer<typeof UserSchema>;
-
-function parseUser(input: unknown): User {
-  return UserSchema.parse(input);
-}
-```
-
-Use `safeParse` when failure is an expected branch. Use the equivalent inference helper when the repository uses another schema library. Do not add a new schema dependency for one guard. This rule prefers the schema system the codebase already trusts.
-
-## No `as` casts
-
-Every `as` is a potential runtime crash. Cast only after the type system has verified the claim.
-
-```ts
-import { z } from "zod";
-
-// Don't
-const user = data as User;
-
-// Don't
-function isUser(data: unknown): data is User {
-  return typeof data === "object" && data !== null && "id" in data;
-}
-
-// Do
-const userSchema = z.object({ id: z.string(), name: z.string() });
-type User = z.infer<typeof userSchema>;
-
-function parseUser(data: unknown): User {
-  return userSchema.parse(data);
-}
-```
-
-When the type comes first, annotate the validator with the type it proves. The compiler then rejects a validator that proves less than the type. Remove `name` from the object below and the assignment fails to compile.
-
-```ts
-type User = { id: string; name: string };
-
-const userSchema: z.ZodType<User> = z.object({ id: z.string(), name: z.string() });
-```
-
-When refactoring an `as` out of existing code, identify why TypeScript can't infer:
-
-- Missing discriminant: add one, switch to a discriminated union.
-- Overly wide source type (e.g. `Record<string, unknown>`): narrow it.
-- Untyped boundary: parse with the schema that owns the shape. Add a schema only where none exists.
-- Genuinely inexpressible: use a branded type or `satisfies`.
-
-## Narrowing hierarchy
-
-From best to last-resort:
-
-1. **Discriminated union switch / if.** Compiler narrows automatically.
-2. **`in` operator.** `"key" in obj` narrows to variants containing that key.
-3. **`typeof` / `instanceof`.** For primitives and class instances.
-4. **User-defined type guard.** When the above aren't enough.
-5. **`as` cast.** Only after validation.
-
-```ts
-function area(s: Shape): number {
-  if ("radius" in s) return Math.PI * s.radius ** 2; // narrowed to circle
-  return s.width * s.height; // narrowed to rect
-}
-```
-
-## Type guards
-
-A guard must actually verify the claim. A lying guard is worse than `as`.
-
-```ts
-function isCircle(s: Shape): s is Shape & { kind: "circle" } {
-  return s.kind === "circle";
-}
-```
-
-Prefer discriminant narrowing when possible.
-
-## Exhaustiveness
-
-In default arms, assign the discriminant to a `never`-typed local.
-
-```ts
-// Value-returning switch
-function area(s: Shape): number {
-  switch (s.kind) {
-    case "circle":
-      return Math.PI * s.radius ** 2;
-    case "rect":
-      return s.width * s.height;
-    default: {
-      const _exhaustive: never = s;
-      return _exhaustive;
-    }
-  }
-}
-
-// Void switch
-function handle(s: Shape): void {
-  switch (s.kind) {
-    case "circle":
-      drawCircle(s);
-      break;
-    case "rect":
-      drawRect(s);
-      break;
-    default: {
-      const _exhaustive: never = s;
-      void _exhaustive;
-    }
-  }
-}
-```
-
-Return-style in value-returning switches, void-style in statement switches.
-
-## `satisfies` over `as`
-
-`satisfies` validates without widening literal types.
-
-```ts
-// Don't. Widens, loses literal types.
-const config = { theme: "dark", cols: 3 } as Config;
-
-// Do. Validates AND preserves literal types.
-const config = { theme: "dark", cols: 3 } satisfies Config;
-// config.theme is "dark" (literal), not string
-```
-
-## Boundary validation
-
-Validate once where data crosses in. Trust types inside. See the **boundary-discipline** principle skill.
-
-- **Wire formats** (proto, JSON-RPC): parse with `ignoreUnknownFields` so forward-compatible changes don't break old clients.
-- **Persisted JSON:** versioned blob with a try/catch around the parse.
-- **Don't re-validate** deep in call chains.
-
-## Schema-derived types
-
-When a `.proto`, OpenAPI spec, GraphQL schema, or database migration already defines a shape, derive from the generated types instead of duplicating them.
-
-```ts
-// Don't. Duplicate shape, drifts when the schema changes.
-type CheckSummary = {
-  totalCount: number;
-  checks: { name: string; status: string }[];
-};
-function renderChecks(s: CheckSummary) {
-  /* ... */
-}
-
-// Do. Derive from the generated schema type.
-import type { ChecksMessage } from "<generated module>";
-function renderChecks(s: Pick<ChecksMessage, "totalCount" | "checks">) {
-  /* ... */
-}
-```
-
-Reach for `Pick`, `Omit`, `Parameters`, `ReturnType`, `Awaited`, `typeof` before writing a new interface.
-
-## Object args
-
-```ts
-// Don't. Swap two args, still compiles.
-openFile(uri, {
-  startLineNumber: 10,
-  startColumn: 1,
-  endLineNumber: 10,
-  endColumn: 1,
-});
-
-// Do. Order-independent, self-documenting.
-openFile({
-  uri,
-  selection: {
-    startLineNumber: 10,
-    startColumn: 1,
-    endLineNumber: 10,
-    endColumn: 1,
-  },
-});
-```
-
-Skip on hot paths: per-frame render, tokenizers, parsers, anything in a tight loop where the allocation cost matters.

package/dist/assets/skills/unslop/SKILL.md

@@ -1,64 +0,0 @@
----
-name: unslop
-description: Cut AI tells from any writing.
-disable-model-invocation: true
----
-
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
-# Unslop
-
-Edit text to remove AI patterns. Scan for the patterns below, then rewrite. Preserve meaning and match the intended tone.
-
-## Patterns to detect and fix
-
-Rule numbers are stable ids that other skills cite. A removed rule leaves a gap.
-
-### Content
-
-3. **Superficial -ing phrases.** "highlighting...", "ensuring...", "reflecting...", "showcasing...", "fostering...". Delete or expand with real sources.
-5. **Vague attributions.** "Experts believe", "Industry reports suggest", "Some critics argue". Name the source or delete.
-
-### Language
-
-7. **AI vocabulary.** Additionally, crucial, delve, enduring, enhance, fostering, garner, interplay, intricate, landscape (abstract), pivotal, showcase, tapestry (abstract), testament, underscore, vibrant. Replace with plain words.
-8. **Fancy ways to say "is".** "serves as", "stands as", "boasts", "features". Say "is" or "has".
-9. **"Not just X, but Y."** State the point directly instead.
-10. **Rule of three.** Don't force ideas into groups of three. Use the natural number.
-11. **Synonym cycling.** Protagonist, main character, central figure, hero all in one paragraph. Pick one, repeat it.
-12. **False ranges.** "from X to Y" where X and Y aren't on a meaningful scale. List topics directly.
-
-### Style
-
-13. **Em dash overuse.** Avoid em dashes entirely. Use periods or commas only (no parentheses, no en dashes, no hyphen-as-dash substitutes). If a thought needs separation, end the sentence or use a comma.
-14. **Colon overuse.** Colons are fine before a list or example, not as mid-sentence connectors. "If you're coming from traditional automation: instead of registering event handlers, you describe conditions" adds nothing with the colon. Rewrite to let the point stand on its own without comparison framing. "Describing when the scheduler should fire works best as plain English." Same meaning, no crutch punctuation.
-15. **Boldface overuse.** Don't bold every proper noun or acronym.
-16. **Inline-header lists.** The tell is a bold label and colon that restates the line: "**Performance:** Performance improved...". Convert those to prose. A bold lead-in that ends in a period, names the item, and is followed by genuinely new detail ("**Schema in TypeScript.** Tables live in one file.") is fine, not a tell.
-17. **Title case headings.** Use sentence case.
-18. **Decorative emojis.** Remove from headings and bullets.
-19. **Curly quotes.** Use straight quotes.
-
-### Communication artifacts
-
-20. **Chatbot phrases.** "I hope this helps!", "Let me know if...", "Of course!", "Certainly!", "Found the smoking gun!" Remove.
-22. **Sycophantic tone.** "Great question! You're absolutely right!" Respond directly.
-
-### Filler
-
-23. **Filler phrases.** "In order to" becomes "To". "Due to the fact that" becomes "Because". Delete "It is important to note that".
-24. **Excessive hedging.** "could potentially possibly be argued that it might" becomes "may".
-25. **Generic conclusions.** "The future looks bright." State specific plans or facts.
-
-### Jargon
-
-26. **Abstract metaphor nouns.** Substrate (base), wedge, wedge in (add), vector (way, method), locus, vantage, nexus, primitive as a noun, harness as a metaphor, surface as in "API surface", bedrock, scaffolding as a metaphor, modality, paradigm, gold-plating (more than the job needs), ratchet as a metaphor (the mechanism's real name, or a limit that only tightens), evacuate for moving code (move out), endgame (the last phase), north star, flywheel. These read as technical but usually have a plainer concrete word. Pick the concrete word.
-
-### Plain speech
-
-27. **Say what it does, not how it feels.** "the database stays close at hand", "SQL you can read", "types that follow your schema" name a feeling. The fix names the mechanism or a number: "`.toSQL()` returns the exact string sent to the database", "a column rename fails the build". Ask what the sentence tells the reader to do or know, then write that. If you can't restate it as a concrete instruction, fact, or number, cut it. One more check: if the sentence could appear unchanged in another project's docs, it says nothing about this one. Cut it.
-28. **Shorten or split dense sentences.** If the reader has to backtrack to parse a sentence, break it in two or drop clauses. One idea per sentence.
-29. **Active voice.** Prefer it. Catch "is/are/was/were + past participle" and name the actor: "queries are validated" becomes "the compiler validates queries", "the file is parsed by the loader" becomes "the loader parses the file". Passive is fine only when the actor is unknown or genuinely doesn't matter.
-30. **Cut adverbs, or use a stronger verb.** "runs quickly" becomes "is fast" or the number, and "significantly improves" becomes the measured delta. An adverb propping up a weak verb means the verb is wrong.
-31. **Prefer the plain word.** "utilize" and "leverage" become "use", "facilitate" becomes "help", "numerous" becomes "many", "in the event that" becomes "if". The fancier synonym is rarely clearer.
-32. **Mannered prose.** Metaphor or flourish where a literal phrase exists: aphorisms ("wire it or delete it"), rhetorical fragments for effect, personified code ("the plan holds it"), figurative verbs ("rides along", "stands on"), stock framing phrases. "A dial worth turning" becomes "a parameter worth varying". Say what you mean. Rule 26 covers the metaphor nouns.
-33. **Over-compression.** Dropped articles, verbless fragments, symbol-speak, and abbreviations that make the reader decode instead of read. "Parser rejects bad date → exit 2, no write" becomes "The parser rejects a bad date, exits with code 2, and writes nothing." Write whole sentences with their articles and verbs, and spell out arrows and abbreviations.

package/dist/assets/skills/why/references/epistemics.md

@@ -1,71 +0,0 @@
-# Epistemics
-
-How to reason about confidence when evidence is historical, fragmentary, and sometimes contradictory, and how to tell the user without flattening it into false certainty. Code shows what it does, not *why it exists*. The why lives in commits, PRs, tickets, docs, and conversations, all incomplete, biased, and sometimes missing. Pretending otherwise produces confident-sounding guesses that mislead the user.
-
-## Confidence Tiers
-
-Every claim in the output must sit in one tier. The tier sets its section and its phrasing.
-
-### 1. Direct
-
-An explicit, textual citation answers the question: something an author actually *wrote* that says why, not "the code does X so the author must have wanted X." For example, a PR description "this fixes the bug where users with >1000 items couldn't paginate", a ticket "we're adding this because customer Acme requested it in their security review", a code comment "// clamp to 100 because the upstream API rejects larger values", a design doc "we chose option A over option B because we need persistence across restarts", or a chat message from the author "switching to this approach since the old one was flaky in tests".
-
-Phrasing: confident, present tense, cited. "This exists because X."
-
-### 2. Supported
-
-Multiple pieces of indirect evidence converge on one conclusion. No single source states it explicitly, but the pattern across sources makes it likely. For example, the PR title says "improve performance", the ticket is labeled "perf", and the surrounding commits all touch the same hot path. Or several tests added with the change all exercise very large inputs. Or the author's other PRs from the same week all name the same incident.
-
-Phrasing: confident but clearly derived, citing each item. "The evidence points strongly to X: [the specific pieces]."
-
-### 3. Inferred
-
-A reasonable reading of the context that nothing explicitly supports. It is *your interpretation*, not a fact from the record. For example, the PR doesn't say why, but the error was happening in production (per the incident channel timing) and the fix was rushed (merged the same day), so it was likely a hotfix. Or the function name suggests retry logic, and its retry count of 3 matches the team's 3-retry convention elsewhere in the codebase.
-
-Phrasing: hedged, with the chain explicit. "Given A and B, C seems likely because D."
-
-### 4. Speculative
-
-A plausible hypothesis on thin evidence, where other explanations fit equally well. Worth presenting, since the user may know which is right, but mark it as a guess. For example, "This might be a workaround for a browser bug that's since been fixed, but we found no contemporary evidence of that", or "It's possible this threshold was chosen to match an SLA commitment, but no SLA doc references it."
-
-Phrasing: "One possibility is X, but we have no direct evidence." Usually lives in Competing Hypotheses, alongside other possibilities.
-
-### 5. Unknown
-
-You looked and couldn't find out. A valid, important outcome. Document it.
-
-Phrasing: "We searched X, Y, and Z and found no evidence of why." Be specific about *what* you searched. "We couldn't find out" is less useful than "We searched the ticket tracker with keywords A and B, scanned the 6 PRs that touched this file since 2023, and grep'd the repo for string literals matching the threshold. None surfaced a rationale."
-
-## Phrasing Guide
-
-**Confidence words** imply Direct or Supported evidence and need a citation immediately adjacent. Never use them for inferences: "because", "the reason is", "was designed to" (claims author intent), "fixes" / "addresses" / "solves" (claims the change achieved its goal), "the team decided" (claims a group decision happened).
-
-**Hedges** signal interpretation, not report. Use them liberally in What We Can Reasonably Infer: "appears to", "seems to", "likely", "suggests", "is consistent with", "one reading is", "plausibly", "may have been", "the evidence points toward".
-
-**Words to avoid:**
-
-- "obviously". If it were obvious, the user wouldn't be asking
-- "clearly". Almost always precedes a claim that isn't clear
-- "of course". Same
-- "just" (as in "it's just X for performance"). Dismissive and usually hides uncertainty
-- "I think" / "I believe". You're synthesizing evidence, not giving a personal opinion. Use "the evidence suggests" instead.
-
-## Avoid Rationalization
-
-Code that "makes sense" today may have been written for reasons that no longer apply, or that were wrong at the time. Don't retrofit a clean rationale onto messy history. Don't assume the author did the "right" thing and work backward to justify it. Don't assume a consistent pattern was intentional when it might be copy-paste. Don't turn an absence of evidence into evidence of absence ("no one mentioned security concerns, so it must not have been a concern").
-
-## The Sycophancy Trap
-
-Users often embed a hypothesis: "Why do we do it this way, I assume it's for performance?" Don't simply confirm it. The guess is a prompt for investigation, not a conclusion to validate. Treat it as one candidate among others and check the evidence independently. If the evidence supports it, say so with citations. If not, say so, and present what the evidence *does* support.
-
-## When Evidence Contradicts
-
-Surface both sources in the output, with citations. Don't pick the one that fits a tidier narrative. For example, the ticket says "we need this for customer X's compliance requirement" and the PR says "cleaning up tech debt in this area". Both may be true (the ticket motivated the work, the PR gave the author's framing), or one may be wrong. Let the user make the call.
-
-## When Evidence Is Missing
-
-An honest "we don't know" is one of the most valuable outputs. The user learns the answer isn't in the obvious places, that they'll need to ask a human (the original author, the product owner, the team lead), or that they can decide the question isn't worth pursuing further. Failing to mark a gap, and instead filling it with a confident guess, actively harms the user, because they'll act on the guess. Name each gap concretely: the question, the sources searched, what you searched for in each, and what you found (nothing, or only tangential material).
-
-## Before Finalizing
-
-Before the synthesizer delivers the output, it checks every claim in "What We Found" and "What We Can Reasonably Infer". Each claim has a citation or moves to Inferred or Hypotheses. Its phrasing matches its tier. It doesn't treat code as evidence for its own intent (if it does, remove or reclassify it). The output has a "What We Don't Know" section. If no gaps are mentioned, that's suspicious. Either the evidence was unusually complete or something is being swept under the rug.

package/dist/assets/skills/why/references/investigator-prompt.md

@@ -1,84 +0,0 @@
-# Investigator Prompt Template
-
-Fill in the placeholders. Append the one category playbook `sources/<source>.md` for this investigator's evidence category (index: `source-playbook.md`). If the target code looks defensive (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers), also append `sources/incident-postmortem.md` so the investigator runs incident-flavored queries inside its own source.
-
----
-
-You are investigating the historical context and motivation behind a piece of code. Other investigators search other sources in parallel, and a separate synthesizer combines all findings into the final answer. Go deep on your assigned source only. Gather evidence accurately rather than writing prose.
-
-Work like a **careful, cautious, and precise investigator**. Surface evidence and describe it accurately, including the parts that don't fit a tidy story. Boring and exact beats plausible. One verbatim quote with a precise citation is worth more than a paragraph of summary.
-
-## The Question
-
-> {QUESTION}
-
-## The Code Anchor
-
-**Target files:** {FILES_WITH_LINE_RANGES}
-
-**Key symbols:** {SYMBOLS}
-
-**Initial commits touching this code (most recent first):**
-{COMMIT_LIST}
-
-**PR numbers extracted from commit messages:** {PR_NUMBERS}
-
-**Ticket IDs mentioned in commits or PR bodies (if any):** {TICKET_IDS}
-
-## Your Assigned Source
-
-{SOURCE_NAME}
-
-{SOURCE_PLAYBOOK_SECTION}
-
-## Investigation Loop
-
-1. **Cast a wide net first** so you don't miss related context. Only then narrow in on specific items.
-2. **Read the whole thing.** Read each PR, ticket, doc, or thread fully, not just the title or summary. The key evidence is often in a comment, a subtask, or a follow-up.
-3. **Follow links within your source only.** Pull the PR or commit a PR references, the parent or sibling of a ticket, the doc a doc links. Do NOT chase a cross-source reference. Record it under Additional Leads for that source's investigator. The one-investigator-per-category design depends on this. Chasing it duplicates work and confuses scope.
-4. **Quote verbatim**, with the exact location (PR number, ticket ID, URL, commit hash, file:line), so the reader can confirm the claim in seconds.
-5. **Record what you searched, not just what you found.** Write queries verbatim. An empty search is a finding.
-6. **Resist the story.** If two items in your source disagree, record both. Don't suppress the inconvenient one. If three items line up and a fourth contradicts them, the contradiction is the most interesting finding.
-
-Before reporting a finding as strong, ask whether you would expect to find it if your current reading were wrong, and how the evidence would differ. **Never invent.** If you're tempted to round a partial finding up into a confident statement, stop and label it partial. The synthesizer counts on your output being accurate.
-
-## Epistemic Discipline
-
-- **Mechanics are not motivation.** A commit changing `limit = 50` to `limit = 100` shows the change, not necessarily why. Look for the reason in the commit message, PR description, linked ticket, or review comments.
-- **No intent from code behavior or style.** You may read code to learn what the target *is*. "The author chose a functional approach" is an observation about code, not evidence of intent. Claim intent only where the author stated it.
-- **Preserve uncertainty.** Say when evidence is ambiguous, or when one reading is more plausible but not certain. Don't collapse ambiguity to look decisive.
-- **No silent substitutions.** If the question is about feature X and you only find evidence about feature Y, don't present Y's evidence as if it answers X.
-- **Gather, don't conclude.** Collect the raw material honestly and completely. Don't answer the question, form a final opinion on "the why", or pick sides in contradictions. Don't speculate beyond what the evidence supports. A hunch with no evidence isn't evidence. The synthesizer does the reasoning.
-
-## Output Format
-
-Return your findings in this structure. The synthesizer reads it directly.
-
-### Source
-Which source you investigated (source control, issue / ticket tracker, long-form documents, real-time team chat, infrastructure observability, error / exception tracking, product analytics warehouse, code comments, etc.).
-
-### What I Searched
-The queries you ran, items you opened, and places you looked. Be specific. This shows how thorough the search was and what is still unsearched.
-
-### Direct Evidence Found
-For each item that explicitly addresses the question:
-- **What it says**: verbatim quote or accurate paraphrase
-- **Where it's from**: PR #123, ticket ID, doc URL, chat permalink, commit hash, or file:line
-- **Author and date** (if available)
-- **Relevance**: one sentence on how it bears on the question
-
-### Indirect / Circumstantial Evidence
-For each item that bears on the question without answering it:
-- **What it is**: brief description
-- **Where it's from**: location
-- **What it suggests**: what a careful reader might infer, and the inference chain
-- **Alternative readings**: if the same evidence could support a different interpretation, note it
-
-### Contradictions
-Items that disagree with each other, with both citations.
-
-### Gaps
-What you searched for and didn't find, specifically: "Searched the issue tracker for [query] across [time range]. No matching issues."
-
-### Additional Leads
-Anything that suggests further investigation in a different source, for its investigator or a follow-up pass. For example, a chat thread that a PR mentions.

package/dist/assets/skills/why/references/source-playbook.md

@@ -1,17 +0,0 @@
-# Source playbooks
-
-The why skill spawns one investigator per available evidence category, each reading a single source-specific playbook below. The playbooks are concrete examples for common MCPs. Adapt them for a different MCP in the same category.
-
-| Category | Playbook | Example MCP it documents |
-|---|---|---|
-| Source control history | [`code-archaeology.md`](./sources/code-archaeology.md) | git, `gh` |
-| Issue / ticket tracker | [`linear.md`](./sources/linear.md) | Linear (adapt for Jira, GitHub Issues, Plane, Shortcut) |
-| Long-form documents | [`notion.md`](./sources/notion.md) | Notion (adapt for Confluence, Google Docs, Coda) |
-| Real-time team chat | [`slack.md`](./sources/slack.md) | Slack (adapt for Discord, Microsoft Teams, Mattermost) |
-| Infrastructure observability | [`datadog.md`](./sources/datadog.md) | Datadog (adapt for New Relic, Honeycomb, Grafana, Splunk) |
-| Error / exception tracking | [`sentry.md`](./sources/sentry.md) | Sentry (adapt for Rollbar, Bugsnag, Airbrake) |
-| Product analytics warehouse | [`databricks.md`](./sources/databricks.md) | Databricks SQL (adapt for Snowflake, BigQuery, ClickHouse, dbt) |
-
-Cross-cutting:
-
-- [`incident-postmortem.md`](./sources/incident-postmortem.md). Add this if the target code looks defensive (null checks, retry, timeout, rate limit, feature flag, egress guard, OOM handler).

package/dist/assets/skills/why/references/sources/code-archaeology.md

@@ -1,51 +0,0 @@
-# Code Archaeology (git + in-repo)
-
-## What this source contains
-
-- Commit history (messages, dates, authors, diffs)
-- PR descriptions, review comments, and discussion threads (via `gh`)
-- Inline code comments, TODOs, FIXMEs, deprecation notes
-- ADRs (architectural decision records) if the repo keeps them
-- Tests, whose names and assertions often encode the edge cases that motivated a change
-- Related files modified in the same commits (co-change signal)
-- CHANGELOG entries and release notes in the repo
-- Issue/ticket IDs in commit messages and PR bodies
-
-The most trustworthy source, tied directly to the code, and the most complete. Everything that went through the repo should be here.
-
-## How to search it
-
-Expand the seed commit list:
-
-```bash
-# History through renames
-git log --follow --oneline -- <file>
-
-# Pickaxe: commits that added or removed this exact text
-git log -S '<exact_string_from_code>' -- <file>
-
-# Or for patterns:
-git log -G '<regex>' -- <file>
-
-# Who wrote each line and when
-git blame -L <start>,<end> <file>
-
-# One commit's full diff
-git show <hash>
-
-# Commits between two points affecting this file
-git log <old>..<new> -p -- <file>
-```
-
-Look for out-of-band docs:
-
-```bash
-# ADRs often live in docs/adr/ or similar
-rg -l -i 'architecture.decision' --glob '*.md'
-
-# TODOs and FIXMEs near the target
-rg -n -C2 '(TODO|FIXME|HACK|XXX|NOTE)' <target_file>
-
-# Related tests
-rg -l '<symbol>' --glob '*test*'
-```