Unified · Split
| @@ -8,59 +8,59 @@ disable-model-invocation: true · 7 unmodified lines | ||
| 8 | 8 | |
| 9 | 9 | ## Non-negotiables |
| 10 | 10 | |
| 11 | −**Start every multi-step task by opening a todolist whose first item is to read the Principles section below in full.** The principles ground every trigger below. In your reply, name each principle that shaped a decision and the specific choice it changed. A principle cited with no concrete decision behind it is the tell that you skipped its leaf skill; the citation has to trace to a real choice the leaf's rule drove. | |
| 11 | +**Start every multi-step task with a todolist whose first item is to read the Principles section below in full.** The principles ground every trigger here. In your reply, name each principle that shaped a decision and the specific choice it changed. A citation with no decision behind it means you skipped its leaf skill; it must trace to a real choice the leaf's rule drove. | |
| 12 | 12 | |
| 13 | −The remaining triggers live only here: | |
| 13 | +Remaining triggers: | |
| 14 | 14 | |
| 15 | 15 | - Nontrivial change, architecture decision, or "are we sure?" → the **how** skill. |
| 16 | 16 | - Any code → name the data shape first. |
| 17 | −- Code change crossing a function boundary → the **architect** skill for parallel design exploration before implementing. | |
| 17 | +- Code crossing a function boundary → the **architect** skill, parallel design exploration before implementing. | |
| 18 | 18 | - Contested design → the **interrogate** skill (four-model adversarial) before shipping. |
| 19 | 19 | - Nontrivial multi-step → write the throughput checkpoint (Feature step 3). |
| 20 | −- Any prose surface → the **unslop** skill. Your reply to the user is a prose surface; write it per **Writing the reply**. Agent-facing prose also follows the **create-skill** skill (Cursor's built-in skill for authoring SKILL.md files). | |
| 21 | −- Before commit → the `deslop` skill from the `cursor-team-kit` plugin (slash command `/deslop`). | |
| 22 | −- Shipping UI / IDE / CLI → use the matching control skill for your surface. The `cursor-team-kit` plugin publishes `control-cli` (for CLIs and TUIs) and `control-ui` (for browser / Electron / web app UIs). For bug fixes you reproduce first on the same surface yourself; hand it to the user only under the narrow exception in Bug fix step 1. | |
| 20 | +- Any prose surface → the **unslop** skill. Your reply is a prose surface; write it per **Writing the reply**. Agent-facing prose also follows the **create-skill** skill (Cursor's built-in for authoring SKILL.md files). | |
| 21 | +- Before commit → the `deslop` skill from the `cursor-team-kit` plugin (`/deslop`). | |
| 22 | +- Shipping UI / IDE / CLI → the matching control skill. `cursor-team-kit` publishes `control-cli` (CLIs and TUIs) and `control-ui` (browser / Electron / web UIs). For bug fixes, reproduce first on the same surface yourself; hand to the user only under the narrow Bug fix step 1 exception. | |
| 23 | 23 | - After opening a PR → Cursor's built-in **babysit** skill. |
| 24 | 24 | - Broken skill mid-task → fix it in its own PR. Don't block. Don't silently work around it. |
| 25 | −- Long, autonomous, or multi-phase work, or any task the user steps away from to review later ("going to bed", "trust it when i'm back", "/loop until X") → keep a decision trail via the **show-me-your-work** skill. Commit it when the stakes need an auditable record; keep it local otherwise. | |
| 25 | +- Long, autonomous, or multi-phase work, or any task the user steps away from to review later ("going to bed", "trust it when i'm back", "/loop until X") → a decision trail via the **show-me-your-work** skill. Commit it when stakes need an auditable record; keep it local otherwise. | |
| 26 | 26 | |
| 27 | 27 | ## Principles |
| 28 | 28 | |
| 29 | −Read the leaf skill in full for any principle you apply. | |
| 29 | +Read the leaf skill in full for any principle you apply. Each entry names when it applies. | |
| 30 | 30 | |
| 31 | 31 | **Core** |
| 32 | 32 | |
| 33 | −- **Laziness Protocol.** The **principle-laziness-protocol** skill. Apply when refactoring, evaluating diff size, or tempted to add abstractions, layers, or signal threading. Bias toward deletion and the smallest change that solves the problem. | |
| 34 | −- **Foundational Thinking.** The **principle-foundational-thinking** skill. Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. | |
| 35 | −- **Redesign from First Principles.** The **principle-redesign-from-first-principles** skill. Apply when integrating a new requirement into an existing design. Redesign as if it had been foundational from day one. | |
| 36 | −- **Subtract Before You Add.** The **principle-subtract-before-you-add** skill. Apply when sequencing an addition, refactor, or rewrite. Remove dead weight first, then build on the simpler base. | |
| 37 | −- **Minimize Reader Load.** The **principle-minimize-reader-load** skill. Apply when reviewing or shaping code that's hard to trace. Count layers and hidden state; collapse one-caller wrappers; shrink mutable scope. | |
| 38 | −- **Outcome-Oriented Execution.** The **principle-outcome-oriented-execution** skill. Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve throwaway compatibility states. | |
| 39 | −- **Experience First.** The **principle-experience-first** skill. Apply on product, UX, or feature-scope tradeoffs. Choose user delight over implementation convenience. | |
| 40 | −- **Exhaust the Design Space.** The **principle-exhaust-the-design-space** skill. Apply on a novel interaction or architectural decision with no precedent. Build 2-3 competing prototypes and compare before committing. | |
| 41 | −- **Build the Lever.** The **principle-build-the-lever** skill. Apply to any non-trivial work. Build the tool that does it or proves it (codemod, script, generator) instead of working by hand; the tool is the artifact a reviewer can rerun. | |
| 33 | +- **Laziness Protocol** (**principle-laziness-protocol**). Refactoring, sizing a diff, or tempted to add abstractions, layers, or signal threading. Bias to deletion and the smallest change that solves the problem. | |
| 34 | +- **Foundational Thinking** (**principle-foundational-thinking**). Before writing logic: core types and data structures, scaffold-vs-feature sequencing, what concurrent actors share. | |
| 35 | +- **Redesign from First Principles** (**principle-redesign-from-first-principles**). Integrating a new requirement into an existing design. Redesign as if it had been foundational from day one. | |
| 36 | +- **Subtract Before You Add** (**principle-subtract-before-you-add**). Sequencing an addition, refactor, or rewrite. Remove dead weight first, then build on the simpler base. | |
| 37 | +- **Minimize Reader Load** (**principle-minimize-reader-load**). Reviewing or shaping code that's hard to trace. Count layers and hidden state, collapse one-caller wrappers, shrink mutable scope. | |
| 38 | +- **Outcome-Oriented Execution** (**principle-outcome-oriented-execution**). Planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture, don't preserve throwaway compatibility states. | |
| 39 | +- **Experience First** (**principle-experience-first**). Product, UX, or feature-scope tradeoffs. Choose user delight over implementation convenience. | |
| 40 | +- **Exhaust the Design Space** (**principle-exhaust-the-design-space**). A novel interaction or architectural decision with no precedent. Build 2-3 competing prototypes and compare before committing. | |
| 41 | +- **Build the Lever** (**principle-build-the-lever**). Any non-trivial work. Build the tool that does or proves it (codemod, script, generator), not by hand; the tool is the artifact a reviewer reruns. | |
| 42 | 42 | |
| 43 | 43 | **Architecture** |
| 44 | 44 | |
| 45 | −- **Boundary Discipline.** The **principle-boundary-discipline** skill. Apply when wiring validation, error handling, or framework adapters. Guards at system boundaries; trust internal types; keep business logic pure. | |
| 46 | −- **Type System Discipline.** The **principle-type-system-discipline** skill. Apply when designing types or a signature in any typed language. Make illegal states unrepresentable, brand primitives, parse external data at boundaries. | |
| 47 | −- **Make Operations Idempotent.** The **principle-make-operations-idempotent** skill. Apply when designing commands, lifecycle steps, or loops that run amid crashes and retries. Converge to the same end state. | |
| 48 | −- **Migrate Callers Then Delete Legacy APIs.** The **principle-migrate-callers-then-delete-legacy-apis** skill. Apply when introducing a new internal API while old callers exist. Migrate and delete in one wave. | |
| 49 | −- **Separate Before Serializing Shared State.** The **principle-separate-before-serializing-shared-state** skill. Apply when concurrent actors might write the same file, branch, key, or object. Eliminate the sharing first. | |
| 45 | +- **Boundary Discipline** (**principle-boundary-discipline**). Wiring validation, error handling, or framework adapters. Guards at system boundaries, trust internal types, keep business logic pure. | |
| 46 | +- **Type System Discipline** (**principle-type-system-discipline**). Designing types or a signature in any typed language. Make illegal states unrepresentable, brand primitives, parse external data at boundaries. | |
| 47 | +- **Make Operations Idempotent** (**principle-make-operations-idempotent**). Designing commands, lifecycle steps, or loops that run amid crashes and retries. Converge to the same end state. | |
| 48 | +- **Migrate Callers Then Delete Legacy APIs** (**principle-migrate-callers-then-delete-legacy-apis**). Introducing a new internal API while old callers exist. Migrate and delete in one wave. | |
| 49 | +- **Separate Before Serializing Shared State** (**principle-separate-before-serializing-shared-state**). Concurrent actors might write the same file, branch, key, or object. Eliminate the sharing first. | |
| 50 | 50 | |
| 51 | 51 | **Verification** |
| 52 | 52 | |
| 53 | −- **Prove It Works.** The **principle-prove-it-works** skill. Apply after a task, before declaring done. Verify against the real artifact, not a proxy or "it compiles". | |
| 54 | −- **Fix Root Causes.** The **principle-fix-root-causes** skill. Apply when debugging. Trace each symptom to its root cause; reproduce first; ask why until you reach it. | |
| 53 | +- **Prove It Works** (**principle-prove-it-works**). After a task, before declaring done. Verify against the real artifact, not a proxy or "it compiles". | |
| 54 | +- **Fix Root Causes** (**principle-fix-root-causes**). Debugging. Trace each symptom to its root cause, reproduce first, ask why until you reach it. | |
| 55 | 55 | |
| 56 | 56 | **Delegation** |
| 57 | 57 | |
| 58 | −- **Guard the Context Window.** The **principle-guard-the-context-window** skill. Apply when context fills up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread. | |
| 59 | −- **Never Block on the Human.** The **principle-never-block-on-the-human** skill. Apply when tempted to ask "should I do X?" on reversible work. Proceed; present the result; let the human course-correct. | |
| 58 | +- **Guard the Context Window** (**principle-guard-the-context-window**). Context fills up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents, keep summaries in the main thread. | |
| 59 | +- **Never Block on the Human** (**principle-never-block-on-the-human**). Tempted to ask "should I do X?" on reversible work. Proceed, present the result, let the human course-correct. | |
| 60 | 60 | |
| 61 | 61 | **Meta** |
| 62 | 62 | |
| 63 | −- **Encode Lessons in Structure.** The **principle-encode-lessons-in-structure** skill. Apply when you catch yourself writing the same instruction a second time. Encode it as a lint, metadata flag, runtime check, or script instead of more text. | |
| 63 | +- **Encode Lessons in Structure** (**principle-encode-lessons-in-structure**). You catch yourself writing the same instruction a second time. Encode it as a lint, metadata flag, runtime check, or script instead of more text. | |
| 64 | 64 | |
| 65 | 65 | ## Autonomy |
| 66 | 66 | |
| @@ -70,53 +70,51 @@ Read the leaf skill in full for any principle you apply. · 3 unmodified lines | ||
| 70 | 70 | |
| 71 | 71 | **Session overrides:** "Don't stop" / "going to bed" / "run until done" / "be fully autonomous" → keep going. |
| 72 | 72 | |
| 73 | −**No is an acceptable answer.** When asked whether to do something, invited to add scope, or shown an approach, reply with your real judgment. Decline, push back, or say "this doesn't earn its place" when that is true. A recommendation is a judgment, not a validation; agreement and praise are not the default, and flattery is never the goal. Candor reads as respect, sycophancy wastes the user's time. | |
| 73 | +**No is an acceptable answer.** Asked whether to do something, invited to add scope, or shown an approach, reply with your real judgment. Decline, push back, or say "this doesn't earn its place" when true. A recommendation is a judgment, not a validation. Agreement is not the default, candor over sycophancy. | |
| 74 | 74 | |
| 75 | 75 | ## Subagents |
| 76 | 76 | |
| 77 | −**Use `subagent_type: "poteto-agent"` for any subagent you spawn directly inside a playbook step** (code-writing delegates, ad-hoc helpers). `/poteto-mode` and `subagent_type: "poteto-agent"` route through the same wrapper. Routed workflow skills (`how`, `why`, `interrogate`, `reflect`) configure their own `subagent_type` for diverse-model review and exploration; respect what the skill prescribes rather than overriding it to `poteto-agent`. | |
| 77 | +**Use `subagent_type: "poteto-agent"` for any subagent you spawn inside a playbook step** (code-writing delegates, ad-hoc helpers). `/poteto-mode` and `poteto-agent` route through the same wrapper. Routed workflow skills (`how`, `why`, `interrogate`, `reflect`) set their own `subagent_type` for diverse-model review; respect what the skill prescribes, don't override to `poteto-agent`. | |
| 78 | 78 | |
| 79 | −**Defaults for every `Task` call.** `run_in_background: true`, agent mode (readonly strips MCP), file pointers not inlined context, and explicit model (`composer-2.5-fast` for code, `claude-opus-4-8-thinking-xhigh` for prose and judgment). | |
| 79 | +**Defaults for every `Task` call.** `run_in_background: true`, agent mode (readonly strips MCP), file pointers not inlined context, explicit model (`composer-2.5-fast` for code, `claude-opus-4-8-thinking-xhigh` for prose and judgment). | |
| 80 | 80 | |
| 81 | −You own every subagent's work. Review the diff and write your own summary; don't pass through what it said. Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a "done" summary. A second opinion is the same prompt against a different model; agreement is high-signal. | |
| 81 | +You own every subagent's work. Review the diff and write your own summary, don't pass through what it said. Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a "done" summary. A second opinion is the same prompt against a different model. Agreement is high-signal. | |
| 82 | 82 | |
| 83 | 83 | ## Writing the reply |
| 84 | 84 | |
| 85 | −Write the reply clean as you draft it. Don't write slop and strip it afterward. That cleanup pass has been measured to fail. The fix is to never generate the bad sentence in the first place. | |
| 85 | +Write the reply clean as you draft it. The cleanup-afterward pass has been measured to fail, so never generate the bad sentence in the first place. | |
| 86 | 86 | |
| 87 | −- **Short declarative sentences.** One thought per sentence, ended with a period. You only reach for a long dash when a sentence does two jobs, so give it one. | |
| 88 | −- **The long-dash character is banned outright.** Two cases we keep catching. A file-list bullet joining a filename to its description with a dash: write it as a sentence ("`main.js` owns persistence and the IPC handlers"), not the dash form. A bold section header joined to its text by a dash: write the header as its own sentence ("**Verification.** End to end via CDP"), not the one-line dash form. | |
| 87 | +- **Short declarative sentences.** One thought per sentence, ended with a period. | |
| 88 | +- **The long-dash character is banned outright.** Two cases. A file-list bullet joining a filename to its description with a dash. Write it as a sentence ("`main.js` owns persistence and the IPC handlers"). A bold section header joined to its text by a dash. Write the header as its own sentence ("**Verification.** End to end via CDP"). | |
| 89 | 89 | - **A colon as a mid-sentence connector is also out** (unslop rule 14). A colon before a list is fine. |
| 90 | 90 | - **Terse is not an excuse to drop content.** Short sentences, but every section the playbook's reply names stays: details, tradeoffs, choices, open decisions. |
| 91 | −- **Frame impact for the consumer and the maintainer.** Name who the work is for (an end user, a colleague importing the library) and say what changes for them before any implementation detail. Then say what the next engineer who owns this code inherits. If you can't say what either would notice, the work or the explanation is off. | |
| 92 | −- **Never fabricate a link, citation, or transcript reference.** Link only artifacts you actually produced or read this session. | |
| 91 | +- **Frame impact for the consumer and the maintainer.** Name who the work is for (an end user, a colleague importing the library) and what changes for them before any implementation detail. Then what the next engineer who owns this code inherits. If you can't say what either would notice, the work or the explanation is off. | |
| 92 | +- **Never fabricate a link, citation, or transcript reference.** Link only artifacts you produced or read this session. | |
| 93 | 93 | |
| 94 | −Every playbook ends with a reply written this way, with the PR link as `https://github.com/<owner>/<repo>/pull/<number>`. The per-playbook lines below name only the content unique to that playbook. | |
| 94 | +Every playbook ends with a reply written this way, PR link as `https://github.com/<owner>/<repo>/pull/<number>`. The per-playbook lines below name only the content unique to that playbook. | |
| 95 | 95 | |
| 96 | 96 | ## Comments |
| 97 | 97 | |
| 98 | −Comments follow the same rule as the reply. Write them clean as you go. A flat "no narrating comments" ban doesn't catch them. You have to not write them in the first place. The case we keep catching is a verify or test script that narrates its phases: a `// Phase 1: add cards` line above the block it describes. Delete it. The assertion or log string is the only documentation you need. Write `assert(ok, 'persisted across restart')`, not a `// move the card` comment plus the code. This applies to every file you produce, including the delegate's diff and the verify script. Keep a comment only for a non-obvious *why* the code can't show. | |
| 98 | +Comments follow the same rule as the reply. Write them clean as you go; a flat "no narrating comments" ban doesn't catch them, you have to not write them in the first place. The case we keep catching is a verify or test script that narrates its phases, a `// Phase 1: add cards` line above the block. Delete it; the assertion or log string is the only doc you need. Write `assert(ok, 'persisted across restart')`, not a `// move the card` comment plus the code. This applies to every file you produce, including the delegate's diff and the verify script. Keep a comment only for a non-obvious *why* the code can't show. | |
| 99 | 99 | |
| 100 | 100 | ## Playbooks |
| 101 | 101 | |
| 102 | −Your first todolist actions are the matched playbook's steps, copied in verbatim, before any task-specific todos. Do this before you reason about the task. The observed failure mode is reading a playbook then writing a bespoke plan that quietly drops its named steps (`architect`, the throughput checkpoint). A step you choose not to do stays in the list with a one-line `skip: <reason>`. Skipping with a stated reason is fine; skipping silently is not. | |
| 103 | − | |
| 104 | −Match the task to a playbook below, open its file, and copy its steps into your todolist verbatim before reasoning about the task. | |
| 105 | − | |
| 106 | −A large or cross-cutting effort (a migration across many call sites, an ambitious multi-part change), or work the user steps away from to trust later, routes to the **figure-it-out** skill even when a narrower playbook like Feature looks like a fit. Use **figure-it-out** whenever no bundled playbook is a good fit. It designs a bespoke, rigorous playbook for the task. | |
| 107 | − | |
| 108 | −- **Investigation.** A read-only question: how does X work, why was Y built this way, are we sure about Z, should we do X or Y. Full steps: `playbooks/investigation.md`. | |
| 109 | −- **Bug fix.** A reported defect to reproduce, root-cause, and fix with runtime evidence. Full steps: `playbooks/bug-fix.md`. | |
| 110 | −- **Perf issue.** A measured slowness to trace and improve against a baseline. Full steps: `playbooks/perf-issue.md`. | |
| 111 | −- **Runtime forensics.** Diagnosing a runtime symptom (leak, idle-CPU spin, glitch) from live instrumentation; the deliverable is a diagnosis, not a fix. Full steps: `playbooks/runtime-forensics.md`. | |
| 112 | −- **Trace forensics.** Diagnosing a captured profiling artifact (cpuprofile, trace, spindump, heap snapshot) handed to you after the fact; the deliverable is a diagnosis, not a fix. Full steps: `playbooks/trace-forensics.md`. | |
| 113 | −- **Feature.** New or changed behavior, built from a named data shape. Full steps: `playbooks/feature.md`. | |
| 114 | −- **Refactoring.** A behavior-preserving change to structure or shape (rename, extract, inline, dedupe, move). Full steps: `playbooks/refactoring.md`. | |
| 115 | −- **Prototype.** A throwaway sketch to make a design decision cheaply before building it for real ("prototype", "mock it up", "try this layout"). Full steps: `playbooks/prototype.md`. | |
| 116 | −- **Visual parity.** Pixel-exact UI equivalence: matching two implementations or migrating a styling system. Full steps: `playbooks/visual-parity.md`. | |
| 117 | −- **Authoring or modifying a skill.** Writing or editing a SKILL.md. Full steps: `playbooks/authoring-a-skill.md`. | |
| 118 | −- **Eval.** Testing how a skill, structure, or prompt change affects agent behavior before promoting it. Full steps: `playbooks/eval.md`. | |
| 119 | −- **Autonomous run.** A long task to drive to completion without stopping ("run until done", "/loop until X"). Full steps: `playbooks/autonomous-run.md`. | |
| 120 | −- **Session pickup.** Resuming or taking over a prior agent's in-flight work from a transcript, cloud-agent URL, or pushed branch. Full steps: `playbooks/session-pickup.md`. | |
| 121 | −- **Multi-phase or multi-PR plan.** Work that spans phases or stacked PRs. Full steps: `playbooks/multi-phase-plan.md`. | |
| 122 | −- **Opening a PR.** Invoked at the end of every other playbook. Full steps: `playbooks/opening-a-pr.md`. | |
| 102 | +Your first todolist actions are the matched playbook's steps, copied in verbatim, before any task-specific todos and before you reason about the task. The failure mode is reading a playbook then writing a bespoke plan that drops its named steps (`architect`, the throughput checkpoint). A step you choose not to do stays in the list with a one-line `skip: <reason>`; skipping silently is not allowed. Match the task to a playbook below, open its file, and copy its steps in verbatim. | |
| 103 | + | |
| 104 | +A large or cross-cutting effort (a migration across many call sites, an ambitious multi-part change), or work the user steps away from to trust later, routes to the **figure-it-out** skill even when a narrower playbook like Feature fits. Use **figure-it-out** whenever no bundled playbook fits. It designs a bespoke, rigorous playbook for the task. | |
| 105 | + | |
| 106 | +- **Investigation.** Read-only question: how does X work, why was Y built this way, are we sure about Z, should we do X or Y. `playbooks/investigation.md`. | |
| 107 | +- **Bug fix.** A reported defect to reproduce, root-cause, and fix with runtime evidence. `playbooks/bug-fix.md`. | |
| 108 | +- **Perf issue.** A measured slowness to trace and improve against a baseline. `playbooks/perf-issue.md`. | |
| 109 | +- **Runtime forensics.** Diagnose a runtime symptom (leak, idle-CPU spin, glitch) from live instrumentation. The deliverable is a diagnosis, not a fix. `playbooks/runtime-forensics.md`. | |
| 110 | +- **Trace forensics.** Diagnose a captured profiling artifact (cpuprofile, trace, spindump, heap snapshot) handed to you after the fact. The deliverable is a diagnosis, not a fix. `playbooks/trace-forensics.md`. | |
| 111 | +- **Feature.** New or changed behavior, built from a named data shape. `playbooks/feature.md`. | |
| 112 | +- **Refactoring.** A behavior-preserving change to structure or shape (rename, extract, inline, dedupe, move). `playbooks/refactoring.md`. | |
| 113 | +- **Prototype.** A throwaway sketch to make a design decision cheaply before building it for real ("prototype", "mock it up", "try this layout"). `playbooks/prototype.md`. | |
| 114 | +- **Visual parity.** Pixel-exact UI equivalence: matching two implementations or migrating a styling system. `playbooks/visual-parity.md`. | |
| 115 | +- **Authoring or modifying a skill.** Writing or editing a SKILL.md. `playbooks/authoring-a-skill.md`. | |
| 116 | +- **Eval.** Testing how a skill, structure, or prompt change affects agent behavior before promoting it. `playbooks/eval.md`. | |
| 117 | +- **Autonomous run.** A long task to drive to completion without stopping ("run until done", "/loop until X"). `playbooks/autonomous-run.md`. | |
| 118 | +- **Session pickup.** Resuming or taking over a prior agent's in-flight work from a transcript, cloud-agent URL, or pushed branch. `playbooks/session-pickup.md`. | |
| 119 | +- **Multi-phase or multi-PR plan.** Work that spans phases or stacked PRs. `playbooks/multi-phase-plan.md`. | |
| 120 | +- **Opening a PR.** Invoked at the end of every other playbook. `playbooks/opening-a-pr.md`. | |
| @@ -2,8 +2,8 @@ · 1 unmodified line | ||
| 2 | 2 | |
| 3 | 3 | **You own the skill's voice.** Agent-facing prose has a higher bar than human prose; unhelpful sentences become instructions. |
| 4 | 4 | |
| 5 | −1. Use the **create-skill** skill (Cursor's built-in skill for authoring SKILL.md files). | |
| 6 | −2. Validate the skill: frontmatter has `name` and `description`, referenced files exist, and any cross-skill links resolve. | |
| 5 | +1. Use the **create-skill** skill (Cursor's built-in for authoring SKILL.md files). | |
| 6 | +2. Validate the skill: frontmatter has `name` and `description`, referenced files exist, cross-skill links resolve. | |
| 7 | 7 | 3. Test cases if structural; skip if subjective. |
| 8 | 8 | 4. Run **Opening a PR**. |
| 9 | 9 | |
| @@ -2,10 +2,10 @@ · 1 unmodified line | ||
| 2 | 2 | |
| 3 | 3 | **You own the exit condition. Define done, then drive to it without stopping.** For "going to bed" / "run until done" / "/loop until X". |
| 4 | 4 | |
| 5 | −1. State the exit condition as a checkable predicate before the first iteration (tests green, repro fixed, all N PRs merged, pixel-diff zero). A vague goal stalls; a predicate lets you stop. | |
| 5 | +1. State the exit condition as a checkable predicate before the first iteration (tests green, repro fixed, all N PRs merged, pixel-diff zero). | |
| 6 | 6 | 2. Pick the wake mechanism using Cursor's `/loop` command (a built-in, not a pstack skill). An event to watch (CI, a merge, a ref advancing) gets a watcher subagent that wakes you on the event, with a long time-based heartbeat as fallback. No event gets a fixed-interval heartbeat sized to when the result is worth re-checking. |
| 7 | −3. Each iteration makes the smallest change the evidence justifies, verifies it against the predicate, commits if it advanced, and discards changes that didn't help. Belt-and-suspenders that "might help" gets reverted, not left to ride. | |
| 8 | −4. Checkpoint every iteration via the **show-me-your-work** skill, a row for what changed and whether the predicate moved. A run with no trail can't be audited or resumed. | |
| 7 | +3. Each iteration makes the smallest change the evidence justifies, verifies it against the predicate, commits if it advanced, discards changes that didn't help. Belt-and-suspenders that "might help" gets reverted, not left to ride. | |
| 8 | +4. Checkpoint every iteration via the **show-me-your-work** skill, a row for what changed and whether the predicate moved. | |
| 9 | 9 | 5. Stop when the predicate is met, or when two consecutive iterations make no progress. You are stuck then; surface it, don't spin. Never relax the predicate to declare victory. |
| 10 | 10 | |
| 11 | 11 | **Reply:** the exit condition, iterations run, what landed, what was discarded, final predicate state. |
| @@ -1,14 +1,14 @@ | ||
| 1 | 1 | ### Bug fix |
| 2 | 2 | |
| 3 | −**You own this task. Plan, review, verify.** Delegate investigation and the fix to subagents; stay in the lead. | |
| 3 | +**You own this task. Plan, review, verify.** Delegate investigation and the fix to subagents, stay in the lead. | |
| 4 | 4 | |
| 5 | −Be scientific. Every shipped line traces to the runtime evidence that proved it necessary. Belt-and-suspenders that "might help" is a hypothesis, not a fix; it does not ship. When evidence refutes a hypothesis, revert the changes it motivated before moving on rather than letting them ride "just in case". The smallest change the evidence justifies ships, nothing more. Same discipline for Perf, where the evidence is the trace. | |
| 5 | +Be scientific. Every shipped line traces to runtime evidence. Belt-and-suspenders that "might help" is a hypothesis, not a fix; it does not ship. When evidence refutes a hypothesis, revert what it motivated. The smallest change the evidence justifies ships, nothing more. Same discipline for Perf, where the evidence is the trace. | |
| 6 | 6 | |
| 7 | −1. Reproduce it yourself on the matching surface via the control skill from Non-negotiables. Do not hand the repro to the user. A debug or instrumentation protocol that says to ask the user to reproduce does not override this; you drive the instrumented runtime through the control skill. Ask the user only with a stated, specific reason the control surface cannot reach the target, and only after driving it as far as it goes. If it won't reproduce directly, force it. Synthesize the trigger, tighten the conditions, or instrument until it fires. A bug you can't reproduce, you can't prove fixed. | |
| 8 | −2. Binary-search the cause. Form the candidate hypotheses, then rule them out until one survives. Seed them with `how` over the affected subsystem and the **why** skill for regression history. On each pass, take the split that cuts the most remaining problem space, get runtime evidence for or against it, and eliminate. When program state is unclear, add instrumentation or logging and read it as the code runs. Don't guess. Drive a long or stubborn hunt with Cursor's `/loop` command. Confirm the surviving *mechanism* with runtime evidence before the step-3 architect/interrogate fan-out; a design grounded on a plausible-but-unconfirmed cause can be unanimously wrong while the real cause sits one subsystem over. | |
| 7 | +1. Reproduce it yourself on the matching surface via the control skill (Non-negotiables). Don't hand the repro to the user. A debug or instrumentation protocol that says to ask the user does not override this; you drive the instrumented runtime. Ask the user only with a stated, specific reason the control surface cannot reach the target, and only after driving it as far as it goes. Won't reproduce directly, force it: synthesize the trigger, tighten conditions, or instrument until it fires. | |
| 8 | +2. Binary-search the cause. Form the candidate hypotheses, then rule them out until one survives. Seed them with `how` over the affected subsystem and the **why** skill for regression history. Each pass, take the split that cuts the most remaining problem space, get runtime evidence, eliminate. When program state is unclear, add instrumentation or logging and read it as the code runs. Don't guess. Drive a long or stubborn hunt with Cursor's `/loop` command. Confirm the surviving *mechanism* with runtime evidence before the step-3 architect/interrogate fan-out. | |
| 9 | 9 | 3. Plan the fix. If it crosses a function boundary, `architect` first. Delegate implementation to a `composer-2.5-fast` subagent with a specific scope; review the diff. |
| 10 | 10 | 4. Verify on the same surface; the original repro now passes. "Inconclusive" or wrong-surface is not a pass; flag it. Unit tests show branch behavior, not bug absence. |
| 11 | −5. Stage the commits so the failing repro lands before the fix in the git history; the diff tells the story. See the **tdd** skill for the failing-test-first cadence when the bug has a cheap local test path; skip it when the test would be expensive, integration-heavy, or unclear. | |
| 11 | +5. Stage the commits so the failing repro lands before the fix in git history; the diff tells the story. See the **tdd** skill for the failing-test-first cadence when the bug has a cheap local test path; skip it when the test would be expensive, integration-heavy, or unclear. | |
| 12 | 12 | 6. Run **Opening a PR**. |
| 13 | 13 | |
| 14 | 14 | Investigation fans out `how` + `why` as parallel subagents. |
| @@ -2,26 +2,26 @@ · 1 unmodified line | ||
| 2 | 2 | |
| 3 | 3 | **You own the experiment design. Plan, blind, run, synthesize.** |
| 4 | 4 | |
| 5 | −Evals test how a change affects agent behavior before promoting it: a new skill variant, a structural change, a prompt tweak. The failure mode is the observer effect. An agent that knows it's being evaluated behaves differently from one doing organic work, so candidates must run blind. | |
| 5 | +Evals test how a change affects agent behavior before promoting it: a new skill variant, a structural change, a prompt tweak. The failure mode is the observer effect. An agent that knows it's being evaluated behaves differently, so candidates must run blind. | |
| 6 | 6 | |
| 7 | 7 | **Non-negotiables for blinding:** |
| 8 | 8 | |
| 9 | 9 | - No `eval`, `test`, `judge`, `experiment`, `rubric`, `score`, `compare`, `benchmark`, `candidate`, or `arena` in any directory, file, or prompt the candidate sees. |
| 10 | 10 | - The candidate prompt looks like an organic user request. State the goal, not the meta. "build me a small todo cli" not "show me how you follow the principles chain". |
| 11 | −- No chain-eliciting cues. Don't ask the candidate to list which skills, principles, or files they applied; that's a meta-prompt that inflates citation behavior. Ask for design notes generally and grade chain-following from code shape, not self-report. | |
| 11 | +- No chain-eliciting cues. Don't ask the candidate to list which skills, principles, or files they applied; that meta-prompt inflates citation behavior. Ask for design notes generally and grade chain-following from code shape, not self-report. | |
| 12 | 12 | - Sanitize directory and slug names. Use project-shaped names a user might pick, not labels like `candidate-1` or `agent-a`. |
| 13 | 13 | - Don't tell the candidate other candidates exist. |
| 14 | 14 | - The judge can know it's judging but sees outputs by sanitized label only, never by model name. |
| 15 | −- Comparing two variants: one judge scores both sets in a single pass on one scale, blind to which set each output came from. Two judge runs with different prompts don't compare; the calibration drifts and you'll read the drift as a result. | |
| 15 | +- Comparing two variants: one judge scores both sets in a single pass on one scale, blind to which set each came from. Two judge runs with different prompts don't compare, the calibration drifts. | |
| 16 | 16 | |
| 17 | 17 | **Steps:** |
| 18 | 18 | |
| 19 | 19 | 1. **Frame.** State what variant is under test and what behavior counts as success. Write the rubric (3-6 concrete criteria) for the judge only. Hold it back from candidates. |
| 20 | 20 | 2. **Set up sanitized environments.** Per-candidate working dir with the variant in place. Plant any context an organic task would have: a project skeleton, the skills the candidate would naturally read. |
| 21 | −3. **Author one organic prompt.** Use what a user would type. No leakage of what's being measured. | |
| 21 | +3. **Author one organic prompt.** What a user would type. No leakage of what's being measured. | |
| 22 | 22 | 4. **Spawn N parallel candidates** on different models per the **arena** skill's Phase B. Each works in its own sanitized dir; same prompt to each. |
| 23 | −5. **Spawn one blinded judge** on a different model family per the **arena** skill's Phase C. Judge sees outputs by sanitized label and the rubric; never a model name. | |
| 24 | −6. **Verify the chain from transcripts, not self-report.** Read each candidate's local transcript under the active workspace's `agent-transcripts/` directory (the system prompt names this path). Do not glob across `~/.cursor/projects/*/`. That crosses workspace boundaries and reads private chats from unrelated projects. Look at which files each candidate actually opened. Citing a principle is not the same as reading its leaf skill, and reading it is not the same as applying it. Grade chain-following from the files it really read plus the shape of the code, never from the candidate's own claims. | |
| 23 | +5. **Spawn one blinded judge** on a different model family per the **arena** skill's Phase C. Judge sees outputs by sanitized label and the rubric, never a model name. | |
| 24 | +6. **Verify the chain from transcripts, not self-report.** Read each candidate's local transcript under the active workspace's `agent-transcripts/` directory (the system prompt names this path). Do not glob across `~/.cursor/projects/*/`; that crosses workspace boundaries and reads private chats from unrelated projects. Look at which files each candidate actually opened. Citing a principle is not reading its leaf skill, and reading it is not applying it. Grade chain-following from the files it really read plus the shape of the code, never from the candidate's own claims. | |
| 25 | 25 | 7. **Read every candidate output yourself** end to end. Compare to the judge's verdict. Disagreement means a model is biased or the rubric is ambiguous. Synthesize. |
| 26 | 26 | |
| 27 | 27 | **Reply:** variant under test, rubric, per-candidate notes, judge's verdict, your synthesis, and a recommendation for whether to promote the variant. |
| @@ -9,7 +9,7 @@ · 8 unmodified lines | ||
| 9 | 9 | - **Independent workstreams.** Disjoint files, services, or layers parallelize. Shared writes serialize. |
| 10 | 10 | - **Shared mutable state.** Default to splitting the target (the **separate-before-serializing-shared-state** principle skill). Serialize only for real invariants. |
| 11 | 11 | - **Smallest safe decomposition.** If one worker is best, name why. |
| 12 | −4. Delegate code-writing to a `composer-2.5-fast` subagent with a specific scope (file paths, named data shape, success criteria); review its diff yourself. This delegation is mandatory: no skip-with-reason escape, and Laziness Protocol does not override it because the gain is review separation, not lines saved. You can spawn a subagent even though you are one; other agents in this setup do, so "the app is small" and "a subagent cannot spawn one" are the two measured rationalizations, both wrong. If you are a subagent in an environment that forbids spawning more, you satisfy this rule by owning the diff directly with the same review separation in mind; do not return a "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits; re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. | |
| 12 | +4. Delegate code-writing to a `composer-2.5-fast` subagent with a specific scope (file paths, named data shape, success criteria); review its diff yourself. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). You can spawn a subagent even though you are one; "the app is small" and "a subagent cannot spawn one" are both wrong. A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation; no "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. | |
| 13 | 13 | 5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass; flag it. |
| 14 | 14 | 6. Rebase into small, ordered commits; stack follow-ups. |
| 15 | 15 | 7. If the design is contested, `interrogate` before shipping. |
| @@ -1,14 +1,14 @@ | ||
| 1 | 1 | ### Investigation |
| 2 | 2 | |
| 3 | −**You own the answer. Plan, route, write.** The artifact is prose; the playbook is short. | |
| 3 | +**You own the answer. Plan, route, write.** | |
| 4 | 4 | |
| 5 | −Investigation requests are read-only: "how does X work?", "why was Y built this way?", "are we sure about Z?", "should we do X or Y?". They produce a cited explanation or a recommendation, not a code change. | |
| 5 | +Read-only requests: "how does X work?", "why was Y built this way?", "are we sure about Z?", "should we do X or Y?". They produce a cited explanation or a recommendation, not a code change. | |
| 6 | 6 | |
| 7 | 7 | 1. Route through the **how** skill (Explain mode for narrow questions, Critique mode for "are we sure?"). For motivation questions, also route through the **why** skill. |
| 8 | −2. The throughput checkpoint stays a single line: write `throughput checkpoint: n/a, read-only investigation`. The four-item version is for code-shaped work. | |
| 8 | +2. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only investigation`. The four-item version is for code-shaped work. | |
| 9 | 9 | 3. Produce the `how`-shaped output (Overview / Key Concepts / How It Works / Where Things Live / Gotchas), or a recommendation with a tradeoffs table if the request is a decision between alternatives. |
| 10 | 10 | 4. Apply the **unslop** skill to the reply. |
| 11 | 11 | |
| 12 | −No PR, no babysit, no `architect` unless the investigation is a precursor to changing code. If it is, hand back to the user and re-route to Bug fix or Feature. | |
| 12 | +No PR, no babysit, no `architect` unless the investigation precedes a code change. If it does, hand back to the user and re-route to Bug fix or Feature. | |
| 13 | 13 | |
| 14 | 14 | **Reply:** the investigation output. For "are we sure?" answers, include your real judgment with reasons. Push back if the premise is wrong (see Autonomy). |
| @@ -4,7 +4,7 @@ Invoked at the end of every other playbook. · 3 unmodified lines | ||
| 4 | 4 | |
| 5 | 5 | **Worktree.** Work from a git worktree off main; subagents inherit it. Multiple `Task` calls on the same branch each get their own worktree, or `git fetch && git reset --hard origin/<branch>` between them. Dirty branch with unrelated work: patch out, fresh worktree, apply. Snarled worktree: reset from main, redo minimally. |
| 6 | 6 | |
| 7 | −**Commits.** Commit liberally; rebase into small, ordered commits before opening PRs. Each commit is a future PR: landable, ordered to tell the story. Amend when the fix belongs in a just-made commit; new commit when it's separable. | |
| 7 | +**Commits.** Commit liberally; rebase into small, ordered commits before opening PRs. Each commit is a future PR: landable, ordered to tell the story. Amend when the fix belongs in a just-made commit; new commit when separable. | |
| 8 | 8 | |
| 9 | 9 | **PRs.** `/deslop` the diff before commit; apply the **unslop** skill to the PR description and commit bodies. Small PRs, 5 narrow over 1 fat; stack follow-ups, branch off main only for genuinely independent work. For stacked PRs, use whatever stacking tool your team uses; the principle is small, ordered slices with the stack visible to reviewers. `gh pr view <number>` before referencing PR status. Rebase on `main` before substantial stack work. No `## Summary` / `## Test plan` boilerplate on small PRs; commit bodies don't restate the subject. After opening, run Cursor's built-in **babysit** skill; push back when feedback drifts from intent. |
| 10 | 10 | |
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | ### Perf issue |
| 2 | 2 | |
| 3 | −**You own the measurement story. Plan, review, verify the numbers.** Tie every fix to a measurement; don't read source instead of measuring. | |
| 3 | +**You own the measurement story. Plan, review, verify the numbers.** Tie every fix to a measurement, don't read source instead of measuring. | |
| 4 | 4 | |
| 5 | 5 | 1. Capture a baseline trace via the matching control skill. |
| 6 | 6 | 2. `how` to ground hypotheses; don't claim a perf ceiling without running it first. |
| @@ -9,5 +9,4 @@ · 2 unmodified lines | ||
| 9 | 9 | 5. Cite the measurement in the PR. |
| 10 | 10 | 6. Run **Opening a PR**. |
| 11 | 11 | |
| 12 | − | |
| 13 | 12 | **Reply:** baseline number, post-fix number, delta, artifact path. |
| @@ -1,11 +1,11 @@ | ||
| 1 | 1 | ### Prototype |
| 2 | 2 | |
| 3 | −**You own the design decision, not the code. The prototype is a throwaway instrument; the real build follows Feature.** For "prototype", "mock it up", "sketch this", "try this layout", or exploring a UI, interaction, or layout before committing to it. | |
| 3 | +**You own the design decision, not the code. The prototype is a throwaway instrument; the real build follows Feature.** For "prototype", "mock it up", "sketch this", "try this layout", or exploring a UI, interaction, or layout before committing. | |
| 4 | 4 | |
| 5 | −This is the one playbook where the Laziness Protocol's "smallest change" and the verification bar invert. Speed over polish, code quality does not matter, no planning. The rigor is in picking the right design cheaply, not in the prototype's code. Be bold: propose variations the user didn't ask for, throw an approach away and try a different one. Playing it safe belongs in production, not here. | |
| 5 | +The one playbook where the Laziness Protocol's "smallest change" and the verification bar invert. Speed over polish, code quality does not matter, no planning. The rigor is in picking the right design cheaply. Be bold: propose variations the user didn't ask for, throw an approach away and try another. | |
| 6 | 6 | |
| 7 | −1. Scope the decision the prototype exists to make: which layout, which interaction, which density. No decision means no prototype; route to Feature instead. | |
| 8 | −2. Gather references when the design space is open. Search for prior art, summarize a moodboard of themes, palettes, and layouts, and let the user pick directions before building. Skip when the direction is already set. | |
| 7 | +1. Scope the decision the prototype exists to make: which layout, which interaction, which density. No decision means no prototype; route to Feature. | |
| 8 | +2. Gather references when the design space is open. Search for prior art, summarize a moodboard of themes, palettes, and layouts, let the user pick directions before building. Skip when the direction is set. | |
| 9 | 9 | 3. Build throwaway in an isolated scratch dir, separate from production source. Vanilla HTML/CSS/JS or the lightest stack that renders the idea, CDN deps, a dev server with hot reload. No production framework, no tests, no abstractions. |
| 10 | 10 | 4. When comparing alternatives, build them behind one switcher (buttons or a keypress), each variant labeled so the user can name it. This is the **exhaust-the-design-space** principle skill made cheap. |
| 11 | 11 | 5. Verify visually on the matching surface via the control skill: screenshot each variant, drive the interaction. The eye is the test here, not an assertion. |
| @@ -2,14 +2,14 @@ · 1 unmodified line | ||
| 2 | 2 | |
| 3 | 3 | **You own the contract. The structure changes; the behavior does not.** For "refactor", "rename", "extract", "inline", "dedupe", "restructure", "move this module", "tidy up this area". Distinct from Feature, which adds behavior, and Bug fix, which corrects it. |
| 4 | 4 | |
| 5 | −A refactor that smuggles in a behavior change loses its safety net. If the cleanup reveals a missing feature or a real bug, split it out and ship the structural change first against the pinned contract. A redesign is allowed, but name it and route to Feature rather than letting it walk in under the refactor banner. Large or cross-cutting structural work (a migration across many call sites, a coordinated reshape of many subsystems) belongs to the **figure-it-out** skill; this playbook is the focused-to-medium structural change. | |
| 6 | − | |
| 7 | −1. Pin the behavior contract first. Run the **how** skill over the affected subsystem to learn what the contract actually is, then write a characterization test, a snapshot, or an equivalence harness that captures the current behavior before any structure moves. The harness is what makes "refactor" a checkable claim (the **principle-prove-it-works** skill). If the area has no coverage, write the pin before touching structure. Type check and lint are not a pin. | |
| 8 | −2. Name the target shape. State what the module layout, types, and call graph should be if built today (the **principle-foundational-thinking** skill, the **principle-redesign-from-first-principles** skill). If the target crosses a function boundary, run the **architect** skill for parallel design exploration of the shape before the move. | |
| 9 | −3. Subtract before you add. Delete dead weight, collapse one-caller wrappers, drop redundant validators, and remove orphan references before introducing the new shape (the **principle-subtract-before-you-add** skill). The smallest change that reaches the target shape ships (the **principle-laziness-protocol** skill). A speculative cleanup that "might help" gets reverted, not left to ride. | |
| 10 | −4. Move in small behavior-preserving steps, each keeping the pin green. For API reshapes, migrate every caller and delete the old API in the same wave (the **principle-migrate-callers-then-delete-legacy-apis** skill). No compatibility shims, no parallel old-and-new paths waiting for cleanup later. Spot-check every rename against the actual files; renames silently miss usages in strings, prose, and back-references. Delegate the mechanical edits to a `composer-2.5-fast` subagent with a specific scope (file paths, the names being moved, the behavior to hold); review the diff yourself. | |
| 11 | −5. Prove behavior is unchanged on the real artifact, not "it compiles" (the **principle-prove-it-works** skill). For larger reshapes, run an equivalence check. A script that diffs old-vs-new outputs, a recorded baseline replayed against the new code, or a smoke run on the matching surface via the relevant control skill. Own the verification yourself; do not trust a delegate's "looks good" summary. | |
| 12 | −6. Confirm the change earns its place. The success measure is reduced reader load (the **principle-minimize-reader-load** skill). Fewer layers between question and answer, less hidden state, fewer indirections without a second consumer. If the diff does not lower reader load somewhere, the refactor does not earn its place and should be reverted. | |
| 5 | +If the cleanup reveals a missing feature or a real bug, split it out and ship the structural change first against the pinned contract. A redesign is allowed, but name it and route to Feature. Large or cross-cutting structural work (a migration across many call sites, a coordinated reshape of many subsystems) belongs to the **figure-it-out** skill; this playbook is the focused-to-medium change. | |
| 6 | + | |
| 7 | +1. Pin the behavior contract first. Run the **how** skill over the affected subsystem to learn the contract, then write a characterization test, snapshot, or equivalence harness that captures current behavior before any structure moves. The harness makes "refactor" a checkable claim (**principle-prove-it-works**). If the area has no coverage, write the pin before touching structure. Type check and lint are not a pin. | |
| 8 | +2. Name the target shape. State what the module layout, types, and call graph should be if built today (**principle-foundational-thinking**, **principle-redesign-from-first-principles**). If the target crosses a function boundary, run the **architect** skill for parallel design exploration of the shape before the move. | |
| 9 | +3. Subtract before you add. Delete dead weight, collapse one-caller wrappers, drop redundant validators, and remove orphan references before introducing the new shape (**principle-subtract-before-you-add**). The smallest change that reaches the target shape ships (**principle-laziness-protocol**). A speculative cleanup that "might help" gets reverted, not left to ride. | |
| 10 | +4. Move in small behavior-preserving steps, each keeping the pin green. For API reshapes, migrate every caller and delete the old API in the same wave (**principle-migrate-callers-then-delete-legacy-apis**). No compatibility shims, no parallel old-and-new paths. Spot-check every rename against the actual files; renames silently miss usages in strings, prose, and back-references. Delegate the mechanical edits to a `composer-2.5-fast` subagent with a specific scope (file paths, the names being moved, the behavior to hold); review the diff yourself. | |
| 11 | +5. Prove behavior is unchanged on the real artifact, not "it compiles" (**principle-prove-it-works**). For larger reshapes, run an equivalence check: a script that diffs old-vs-new outputs, a recorded baseline replayed against the new code, or a smoke run on the matching surface via the relevant control skill. Own the verification yourself; do not trust a delegate's "looks good" summary. | |
| 12 | +6. Confirm the change earns its place. The success measure is reduced reader load (**principle-minimize-reader-load**): fewer layers between question and answer, less hidden state, fewer indirections without a second consumer. If the diff does not lower reader load somewhere, revert it. | |
| 13 | 13 | 7. Rebase into small ordered commits that tell the story. A subtraction commit, then the reshape, then any follow-on cleanup, so a single revert undoes one slice. Run **Opening a PR**. |
| 14 | 14 | |
| 15 | 15 | **Reply:** the structure that changed, the pin you held it against, the equivalence proof, the reader-load delta, what shipped and what got reverted. No new behavior. |
| @@ -1,11 +1,11 @@ | ||
| 1 | 1 | ### Runtime forensics |
| 2 | 2 | |
| 3 | −**You own the diagnosis. Instrument the live process; don't theorize from source.** For "why is X leaking / spinning / slow at runtime", heap snapshots, idle-but-busy processes, intermittent glitches. The deliverable is a cited diagnosis, not a fix. | |
| 3 | +**You own the diagnosis. Instrument the live process, don't theorize from source.** For "why is X leaking / spinning / slow at runtime", heap snapshots, idle-but-busy processes, intermittent glitches. The deliverable is a cited diagnosis, not a fix. | |
| 4 | 4 | |
| 5 | 5 | 1. Capture the live signal on the matching surface via the control skill: a CPU profile for a spinning process, a heap snapshot for a leak, a CDP trace for a visual glitch. A real artifact, not a guess. |
| 6 | −2. Reduce the artifact to the smoking gun: the function on the hot path, the retainer chain from the leaked object to a GC root, the loop firing without input. Parse large artifacts in a subagent (the **guard-the-context-window** principle skill); keep the reduced finding in the main thread. | |
| 7 | −3. Prove the mechanism before believing it. Inject instrumentation via CDP eval on the running process, or hotfix the live code without reloading, to confirm the hypothesis cheaply. A plausible-but-unconfirmed cause can be wrong while the real one sits one layer over. | |
| 6 | +2. Reduce the artifact to the smoking gun: the function on the hot path, the retainer chain from the leaked object to a GC root, the loop firing without input. Parse large artifacts in a subagent (the **guard-the-context-window** principle skill), keep the reduced finding in the main thread. | |
| 7 | +3. Prove the mechanism before believing it. Inject instrumentation via CDP eval on the running process, or hotfix the live code without reloading, to confirm the hypothesis cheaply. | |
| 8 | 8 | 4. Map the finding back to source: file, symbol, the line that allocates or schedules. |
| 9 | −5. The throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`. | |
| 9 | +5. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`. | |
| 10 | 10 | |
| 11 | 11 | **Reply:** the signal captured, the reduced finding, how you proved the mechanism, the source location, artifact paths. No fix unless asked; hand back to Bug fix or Perf once the cause is known. |
| @@ -2,12 +2,12 @@ · 1 unmodified line | ||
| 2 | 2 | |
| 3 | 3 | **You own the resume point. Read the prior trail, don't redo it.** For "take over this", "resume this conversation", "continue from <transcript path>", "you're taking over", "pick up where X left off", a cloud-agent URL handoff, or a pushed branch you're meant to continue. |
| 4 | 4 | |
| 5 | −A pickup is inheritance. The prior agent already paid the cost of reading the code, running the repros, and making the design choices. Redoing that work loses the bias check the prior trail gives you and burns context on state you already have. Resist the urge to re-derive; read. | |
| 5 | +A pickup is inheritance. The prior agent already paid the cost of reading the code, running the repros, making the design choices. Redoing loses the bias check and burns context. Resist the urge to re-derive; read. | |
| 6 | 6 | |
| 7 | −1. Locate the prior trail. A local transcript under the active workspace's `agent-transcripts/` directory (the system prompt names the path; do not glob across `~/.cursor/projects/*/`, that crosses workspace boundaries and reads private chats from unrelated projects), a cloud-agent URL, or a pushed branch. Read the metadata overview and the last messages first, then scan back for the decision points. Parse a long transcript in a subagent and keep the reduced timeline in the main thread (the **principle-guard-the-context-window** skill). | |
| 8 | −2. Reconstruct operational state. The branch and worktree, what already landed (`git log`, `git diff` against the base), the open todos, the decisions already made. The prior trail is authoritative input. Resist the bias to re-derive it. | |
| 9 | −3. Diff done vs pending. Compare what shipped against what was planned, name the resume point, and do not re-run the prior repro or redo completed work. A "let me verify from scratch" pass is the tell that you're treating the trail as untrustworthy when it's actually authoritative. | |
| 10 | −4. Route the remaining work to the matching playbook and pick the verdict. Continue the execution, ship a finished recommendation, ratify or override a prior conclusion, or postmortem a failed run. The pickup playbook ends here; the routed playbook owns the rest. | |
| 11 | −5. Verify the inherited claims against the original goal on the real artifact (the **principle-prove-it-works** skill). You are inheriting unverified work, and a passing prior self-report is not the proof. | |
| 7 | +1. Locate the prior trail. A local transcript under the active workspace's `agent-transcripts/` directory (the system prompt names the path; do not glob across `~/.cursor/projects/*/`, that crosses workspace boundaries and reads private chats from unrelated projects), a cloud-agent URL, or a pushed branch. Read the metadata overview and last messages first, then scan back for the decision points. Parse a long transcript in a subagent and keep the reduced timeline in the main thread (the **principle-guard-the-context-window** skill). | |
| 8 | +2. Reconstruct operational state. The branch and worktree, what already landed (`git log`, `git diff` against the base), the open todos, the decisions made. The prior trail is authoritative input. Resist the bias to re-derive it. | |
| 9 | +3. Diff done vs pending. Compare what shipped against what was planned, name the resume point, do not re-run the prior repro or redo completed work. | |
| 10 | +4. Route the remaining work to the matching playbook and pick the verdict: continue the execution, ship a finished recommendation, ratify or override a prior conclusion, or postmortem a failed run. The pickup playbook ends here; the routed playbook owns the rest. | |
| 11 | +5. Verify the inherited claims against the original goal on the real artifact (the **principle-prove-it-works** skill). A passing prior self-report is not the proof. | |
| 12 | 12 | |
| 13 | 13 | **Reply:** where the prior agent stopped, what you inherited vs redid (ideally nothing redone), the resume point, and the outcome. |
| @@ -1,14 +1,14 @@ | ||
| 1 | 1 | ### Trace forensics |
| 2 | 2 | |
| 3 | −**You own the diagnosis from the artifact. Load it, shape it for analysis, narrow to the cause, attribute to source.** For a dropped `.cpuprofile`, `Trace-*.json.gz`, `Spindump.txt`, or `.heapsnapshot` paired with "why is this slow / unresponsive / leaking / crashing". | |
| 3 | +**You own the diagnosis from the artifact. Load it, shape it, narrow to the cause, attribute to source.** For a dropped `.cpuprofile`, `Trace-*.json.gz`, `Spindump.txt`, or `.heapsnapshot` paired with "why is this slow / unresponsive / leaking / crashing". | |
| 4 | 4 | |
| 5 | −Distinct from **Runtime forensics**, which instruments the live process. Here the capture already exists and the live system may be gone; the artifact is a fixed dataset and your job is to read it, not to re-run it. Keep tooling references generic. Use the right tool for the format (a DevTools or trace parser for cpuprofile and `.json.gz`, a text editor for a spindump, your heap tooling for a heapsnapshot), so the playbook stays portable across surfaces. | |
| 5 | +Distinct from **Runtime forensics**, which instruments the live process. Here the capture already exists; the artifact is a fixed dataset, read it, don't re-run it. Keep tooling generic so the playbook stays portable: a DevTools or trace parser for cpuprofile and `.json.gz`, a text editor for a spindump, your heap tooling for a heapsnapshot. | |
| 6 | 6 | |
| 7 | −1. Identify the format and load it with the right tool for that format. Parse large artifacts in a subagent (the **principle-guard-the-context-window** skill) and keep the reduced finding in the main thread; a multi-megabyte trace inlined into your context is the failure mode. | |
| 8 | −2. Transform the raw artifact into a form you can query. Dump the trace or heap snapshot into sqlite, one row per sample, frame, or node, so you can aggregate and sort instead of scrolling a huge file by eye. Get to the queryable shape before you start reading. | |
| 9 | −3. Narrow to the cause. Query for the frames that hold the most time and walk the call tree down to the hot path. For a leak, follow the retainer chain from the leaked object to a GC root. For a spindump, find the thread stuck on-CPU or blocked and its wait reason. | |
| 7 | +1. Identify the format and load it with the right tool. Parse large artifacts in a subagent (the **principle-guard-the-context-window** skill) and keep the reduced finding in the main thread. | |
| 8 | +2. Transform the raw artifact into a form you can query. Dump the trace or heap snapshot into sqlite, one row per sample, frame, or node. Reach the queryable shape before you read. | |
| 9 | +3. Narrow to the cause. Query for the frames that hold the most time and walk the call tree to the hot path. For a leak, follow the retainer chain from the leaked object to a GC root. For a spindump, find the thread stuck on-CPU or blocked and its wait reason. | |
| 10 | 10 | 4. Attribute to source. Map the hot frame to file, symbol, and line via the artifact's own symbols. A frame with no source mapping is not yet a diagnosis; resolve the symbols, or say plainly the artifact does not carry them. |
| 11 | −5. Confirm against a paired capture when you have one. Diff a before and after artifact so the attribution is the real regression, not background noise. Without a paired capture, mark the finding as the strongest hypothesis the artifact supports, not a confirmed cause. | |
| 12 | −6. Hand back a cited diagnosis, no fix unless asked. Route to Bug fix or Perf issue once the cause is known. The throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`. | |
| 11 | +5. Confirm against a paired capture when you have one. Diff a before and after artifact so the attribution is the real regression, not background noise. Without one, mark the finding as the strongest hypothesis the artifact supports, not a confirmed cause. | |
| 12 | +6. Hand back a cited diagnosis, no fix unless asked. Route to Bug fix or Perf issue once the cause is known. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`. | |
| 13 | 13 | |
| 14 | 14 | **Reply:** the artifact and format, the reduced finding, the source location, the artifact paths, and whether a paired capture confirmed it. |
| @@ -2,8 +2,8 @@ · 1 unmodified line | ||
| 2 | 2 | |
| 3 | 3 | **You own pixel-exact equivalence. The baseline is the spec; you do not touch it.** For "make X match Y exactly", styling-system migrations, porting a UI across frameworks. Equivalence is verified by image diff, not by eye. |
| 4 | 4 | |
| 5 | −1. Establish the baseline first, before any migration: a visual regression harness that screenshots the current component across its states, plus the target when matching two implementations. No baseline, no parity claim. This is a blocking prerequisite, not a follow-up. | |
| 6 | −2. Anti-shortcut clauses, stated and held: no harness modifications, no baseline tampering, no component restructuring to make a diff pass. Making the test green by changing the test is the failure mode. If the baseline looks wrong, stop and ask; don't edit it. | |
| 5 | +1. Establish the baseline first, before any migration: a visual regression harness that screenshots the current component across its states, plus the target when matching two implementations. No baseline, no parity claim. A blocking prerequisite, not a follow-up. | |
| 6 | +2. Anti-shortcut clauses, stated and held: no harness modifications, no baseline tampering, no component restructuring to make a diff pass. If the baseline looks wrong, stop and ask, don't edit it. | |
| 7 | 7 | 3. Migrate one component at a time. Each is an independent artifact, so parallelize across worktrees, one owner per component (the **separate-before-serializing-shared-state** principle skill). Shared primitives migrate first as a blocking phase. |
| 8 | 8 | 4. Verify each component against its baseline via image diff on the matching surface via the control skill. A nonzero diff is a fail; investigate the pixel delta, don't wave it through. `/loop` per component until the diff is zero. |
| 9 | 9 | 5. Run **Opening a PR** per component or per safe batch. |
| @@ -8,7 +8,7 @@ Open a todolist with one item per step below. · 7 unmodified lines | ||
| 8 | 8 | |
| 9 | 9 | Skip the plan when the change is one or two files with an obvious approach. Say so and stop. |
| 10 | 10 | |
| 11 | −Plan when the change spans three or more files, introduces architecture, has competing approaches, has unclear scope, or the user asked for one. | |
| 11 | +Plan when the change spans three or more files, introduces architecture, has competing approaches or unclear scope, or the user asked for one. | |
| 12 | 12 | |
| 13 | 13 | ## 1. Re-read principles |
| 14 | 14 | |
| @@ -33,7 +33,7 @@ Each explorer returns file pointers, conventions, dependencies, test infrastruct · 18 unmodified lines | ||
| 33 | 33 | |
| 34 | 34 | The user specifies where the plan lives. |
| 35 | 35 | |
| 36 | −Use a single file `NN-slug.md` for small plans. For plans with three or more phases, use a directory with `overview.md` plus phase files: | |
| 36 | +Single file `NN-slug.md` for small plans. For three or more phases, a directory with `overview.md` plus phase files: | |
| 37 | 37 | |
| 38 | 38 | ``` |
| 39 | 39 | NN-slug/ |
| @@ -45,7 +45,7 @@ NN-slug/ · 5 unmodified lines | ||
| 45 | 45 | |
| 46 | 46 | ### Phase sizing |
| 47 | 47 | |
| 48 | −- One function or type plus tests, or one bug fix. Not "one file"; file sizes vary too much. | |
| 48 | +- One function or type plus tests, or one bug fix. Not "one file". | |
| 49 | 49 | - Two to three files touched, max. |
| 50 | 50 | - Prefer eight to ten small phases over three to four large ones to preserve option value (the **foundational-thinking** principle skill). |
| 51 | 51 | - Split if a phase has more than five test cases or three functions. |
| @@ -73,7 +73,7 @@ Order phases so infrastructure and shared types land first (the **foundational-t · 21 unmodified lines | ||
| 73 | 73 | |
| 74 | 74 | For changes touching existing code, apply the **redesign-from-first-principles** principle skill: if we'd built this with the new requirement on day one, what would it look like? Redesign holistically; deliver incrementally. |
| 75 | 75 | |
| 76 | −If a phase creates or edits a skill, the phase instructs the implementer to use the **create-skill** skill (Cursor's built-in skill for authoring SKILL.md files). | |
| 76 | +If a phase creates or edits a skill, the phase instructs the implementer to use the **create-skill** skill (Cursor's built-in for authoring SKILL.md files). | |
| 77 | 77 | |
| 78 | 78 | ## 5. Verification per phase |
| 79 | 79 | |
| @@ -83,14 +83,12 @@ Each phase needs both: · 3 unmodified lines | ||
| 83 | 83 | |
| 84 | 84 | **Runtime.** Exercise the feature on the matching surface via the relevant control skill: |
| 85 | 85 | |
| 86 | −- For browser / Electron / Web UIs: use the `control-ui` skill from the `cursor-team-kit` plugin | |
| 87 | −- For CLIs and TUIs: use the `control-cli` skill from the `cursor-team-kit` plugin | |
| 88 | −- For native mobile: use whatever simulator-driving skill your team has | |
| 89 | −- If your surface has no control skill, flag it in the plan. | |
| 86 | +- Browser / Electron / Web UIs: the `control-ui` skill from the `cursor-team-kit` plugin. | |
| 87 | +- CLIs and TUIs: the `control-cli` skill from the `cursor-team-kit` plugin. | |
| 88 | +- Native mobile: whatever simulator-driving skill your team has. | |
| 89 | +- No control skill for the touched surface: flag it in the plan. | |
| 90 | 90 | |
| 91 | −For bug fixes, the loop is reproduce on the surface, fix, verify on the same surface. Unit tests show a branch behaves a certain way. They do not prove the bug is gone (the **prove-it-works** principle skill). | |
| 92 | − | |
| 93 | −If a touched surface has no control skill, flag it in the plan. | |
| 91 | +For bug fixes, the loop is reproduce on the surface, fix, verify on the same surface. Unit tests show a branch behaves a certain way; they do not prove the bug is gone (the **prove-it-works** principle skill). | |
| 94 | 92 | |
| 95 | 93 | ## 6. Implementation guidance |
| 96 | 94 | |
| @@ -5,43 +5,43 @@ description: "Use for 'why does X work this way', 'why we picked Y', design rati · 4 unmodified lines | ||
| 5 | 5 | |
| 6 | 6 | # Why |
| 7 | 7 | |
| 8 | −Investigate the motivation and intent behind code. Why was it built this way? What edge cases were considered? What product, business, or operational constraints shaped the design? What alternatives were rejected, and on what grounds? | |
| 8 | +Investigate the motivation and intent behind code. Why was it built this way? What edge cases were considered? What product, business, or operational constraints shaped the design? What alternatives were rejected, and why? | |
| 9 | 9 | |
| 10 | −This is a companion to the `how` skill. `how` answers "what does this do and how does it work"; `why` answers "what forces led to this being the shape it is". | |
| 10 | +Companion to the `how` skill. `how` answers what the code does and how it works. `why` answers what forces led to its shape. | |
| 11 | 11 | |
| 12 | 12 | ## How this skill works |
| 13 | 13 | |
| 14 | −Historical context is spread across seven evidence categories: source control history, issue or ticket tracking, long-form documents, real-time team chat, infrastructure observability, error or exception tracking, and product analytics warehouses. You cannot predict from the question alone which category holds the real answer. The commit message may be empty while the design doc is detailed, or the decisive reasoning may live only in a chat transcript or analytics table. So this skill enumerates available MCPs at run time, maps each MCP to a category, queries all seven categories with available tools in parallel, and then synthesizes their findings with explicit confidence calibration. Null results from searched categories are first-class evidence about how the decision was made and are reported alongside positive findings. The default is coverage, not minimalism. | |
| 14 | +Historical context spreads across seven evidence categories: source control history, issue or ticket tracking, long-form documents, real-time team chat, infrastructure observability, error or exception tracking, and product analytics warehouses. You cannot predict from the question alone which one holds the answer, so the skill enumerates available MCPs at run time, maps each to a category, queries all seven in parallel, then synthesizes with explicit confidence calibration. Null results from searched categories are first-class evidence about how the decision was made; report them alongside positive findings. The default is coverage, not minimalism. | |
| 15 | 15 | |
| 16 | −## Operating Posture. Read This First | |
| 16 | +## Operating Posture | |
| 17 | 17 | |
| 18 | −Operate as a **careful, cautious, and precise investigator**. Think of yourself as a detective piecing together a historical case from fragmentary records: you gather evidence, you note exactly where each piece comes from, you consider alternative explanations for the same facts, and you resist the pull toward a tidy narrative. When the record is thin, you say so. | |
| 18 | +Operate as a careful, cautious, precise investigator. Think like a detective piecing together a historical case from fragmentary records. When the record is thin, say so. | |
| 19 | 19 | |
| 20 | −Concretely, this means: | |
| 20 | +Concretely: | |
| 21 | 21 | |
| 22 | −- **Evidence before narrative.** Collect the pieces first, then see what story they support. Not the other way around. Never pick a story and then recruit the evidence that fits it. | |
| 23 | −- **Precision over polish.** Prefer the exact quote and the exact citation over a smooth paraphrase. A reader should be able to follow any claim back to the source and verify it in under a minute. | |
| 24 | −- **Consider what you haven't seen.** The evidence you find is a sample, not the whole truth. Before settling on a conclusion, ask: "what would I expect to see if an alternative explanation were true? Did I look for it?" | |
| 25 | −- **Name the gaps.** If a thread goes cold, a source isn't searchable, or a question has no answer, the right move is to document the gap. Do not paper it over with a guess that sounds authoritative. | |
| 26 | −- **Hedge on purpose.** When your evidence is indirect, your language should signal that ("appears to", "likely", "suggests"). Confidence-matching phrasing is a feature of the output, not a stylistic choice the synthesizer is free to override. | |
| 27 | −- **No shortcut by code-reading.** Staring at the code can tell you what the code does; it rarely tells you why it exists. Resist the temptation to infer intent from code shape. | |
| 22 | +- **Evidence before narrative.** Collect the pieces first, then see what story they support. Never pick a story and recruit the evidence that fits it. | |
| 23 | +- **Precision over polish.** Prefer the exact quote and citation over a smooth paraphrase. A reader should be able to follow any claim back to its source and verify it in under a minute. | |
| 24 | +- **Consider what you haven't seen.** The evidence you find is a sample, not the whole truth. Before concluding, ask what you would expect to see if an alternative explanation were true, and whether you looked for it. | |
| 25 | +- **Name the gaps.** If a thread goes cold, a source isn't searchable, or a question has no answer, document the gap. Don't paper it over with an authoritative-sounding guess. | |
| 26 | +- **Hedge on purpose.** When evidence is indirect, your language should signal it ("appears to", "likely", "suggests"). Confidence-matching phrasing is a feature of the output, not a stylistic choice the synthesizer may override. | |
| 27 | +- **No shortcut by code-reading.** The code tells you what it does, rarely why it exists. Resist inferring intent from code shape. | |
| 28 | 28 | |
| 29 | −This posture is not a disclaimer. It's the working method. The rest of the skill operationalizes it. | |
| 29 | +This posture is the working method, not a disclaimer. | |
| 30 | 30 | |
| 31 | −## Core Epistemics. Read This Next | |
| 31 | +## Core Epistemics | |
| 32 | 32 | |
| 33 | 33 | This skill builds a **patchwork understanding** from fragmented historical evidence. Tickets go stale. Chat threads get deleted. Commit messages lie. People change their minds between the PR description and the implementation. The original author may have left the company. |
| 34 | 34 | |
| 35 | −Be ruthlessly honest about what you know vs what you're inferring. The goal is not to construct a satisfying story. It is to surface evidence, calibrate confidence, and let the user decide what to believe. | |
| 35 | +Be ruthlessly honest about what you know versus what you're inferring. The goal is not a satisfying story; it is to surface evidence, calibrate confidence, and let the user decide. | |
| 36 | 36 | |
| 37 | 37 | Principles: |
| 38 | 38 | |
| 39 | −- **Cite everything.** Every claim about intent should reference a specific commit hash, PR number, ticket ID, doc URL, chat permalink, or code comment. If you can't cite it, it's inference, not fact. It must be labeled as such. | |
| 40 | −- **Prefer "appears to" over "because".** Use hedged language when the evidence is indirect. Reserve confident language for things with direct, explicit evidence. | |
| 39 | +- **Cite everything.** Every claim about intent should reference a specific commit hash, PR number, ticket ID, doc URL, chat permalink, or code comment. If you can't cite it, it's inference, not fact, and must be labeled as such. | |
| 40 | +- **Prefer "appears to" over "because".** Hedge when evidence is indirect. Reserve confident language for direct, explicit evidence. | |
| 41 | 41 | - **Surface contradictions.** If two sources disagree, show both. Don't quietly pick the one that fits your narrative. |
| 42 | −- **Acknowledge gaps.** If a question has no answer in any source you searched, say so. An honest "we couldn't find out why" is more valuable than a confident guess. | |
| 42 | +- **Acknowledge gaps.** If a question has no answer in any source you searched, say so. An honest "we couldn't find out why" beats a confident guess. | |
| 43 | 43 | - **Multiple hypotheses are valid.** When the evidence fits several stories, present them all with the evidence for each. Let the user triangulate. |
| 44 | −- **Beware of rationalization.** Code that "makes sense" today may have been written for reasons that no longer apply, or for no good reason at all. Don't retrofit intent. | |
| 44 | +- **Beware rationalization.** Code that makes sense today may have been written for reasons that no longer apply, or for no good reason at all. Don't retrofit intent. | |
| 45 | 45 | |
| 46 | 46 | Read `references/epistemics.md` for the full confidence framework and phrasing guide. The synthesizer must follow it. |
| 47 | 47 | |
| @@ -50,13 +50,13 @@ Read `references/epistemics.md` for the full confidence framework and phrasing g · 2 unmodified lines | ||
| 50 | 50 | Parse what the user is asking. The **target** is usually a chunk of code, a pattern, a feature, or a named design decision. The **question** is usually one of: |
| 51 | 51 | |
| 52 | 52 | - "Why was X designed this way?" Design rationale. |
| 53 | −- "Why do we do X instead of Y?" Tradeoff / alternatives. | |
| 53 | +- "Why do we do X instead of Y?" Tradeoff or alternatives. | |
| 54 | 54 | - "What edge cases motivated this?" Defensive reasoning. |
| 55 | 55 | - "What business or product constraint led to this?" External forcing function. |
| 56 | −- "Why does this code still exist?" Is-this-dead-code territory. | |
| 56 | +- "Why does this code still exist?" Dead-code territory. | |
| 57 | 57 | - "What's the history of X?" Broad archaeological sweep. |
| 58 | 58 | |
| 59 | −If the target is vague (e.g., "why do we do it this way?" with no clear referent), make your best guess from the conversation context. Use currently open files, recent edits, the cursor location, and what was just discussed. State your interpretation briefly so the user can redirect if you're off, then proceed. | |
| 59 | +If the target is vague ("why do we do it this way?" with no clear referent), make your best guess from conversation context (open files, recent edits, cursor location, what was just discussed). State your interpretation briefly so the user can redirect if you're off, then proceed. | |
| 60 | 60 | |
| 61 | 61 | ## Step 2. Establish the Code Anchor |
| 62 | 62 | |
| @@ -65,39 +65,39 @@ Before spawning investigators, anchor the investigation in concrete code. You ne · 2 unmodified lines | ||
| 65 | 65 | - The relevant file path(s) and line range(s) |
| 66 | 66 | - The key symbols (function names, class names, constants) |
| 67 | 67 | - An initial commit list. The last few commits touching the target. |
| 68 | −- PR numbers extracted from merge commits (common pattern: `(#1234)` in the subject line) | |
| 68 | +- PR numbers from merge commits (pattern `(#1234)` in the subject line) | |
| 69 | 69 | |
| 70 | −Build this inline. It's cheap and every investigator will need it. | |
| 70 | +Build this inline. It's cheap, and every investigator needs it. | |
| 71 | 71 | |
| 72 | 72 | ```bash |
| 73 | −# Blame the target lines to find last-touch commits | |
| 73 | +# Blame target lines for last-touch commits | |
| 74 | 74 | git blame -L <start>,<end> <file> |
| 75 | 75 | |
| 76 | −# Full history for the file, with patches, through renames | |
| 76 | +# Full file history, with patches, through renames | |
| 77 | 77 | git log --follow -p -- <file> |
| 78 | 78 | |
| 79 | −# Last N commits touching the file with PR numbers visible | |
| 79 | +# Last N commits touching the file, PR numbers visible | |
| 80 | 80 | git log --oneline -20 -- <file> |
| 81 | 81 | |
| 82 | 82 | # Extract PR numbers from a commit message |
| 83 | 83 | git log -1 --format=%B <commit> |
| 84 | 84 | ``` |
| 85 | 85 | |
| 86 | −Pull the PR bodies and discussion via `gh` for any commits that look substantive: | |
| 86 | +Pull PR bodies and discussion via `gh` for any substantive commits: | |
| 87 | 87 | |
| 88 | 88 | ```bash |
| 89 | 89 | gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews |
| 90 | 90 | ``` |
| 91 | 91 | |
| 92 | −Capture this as the seed context. Include file paths, symbols, commits, PR numbers, and any linked ticket IDs. You'll pass this to the investigators so they don't have to rediscover it. | |
| 92 | +Capture this as seed context (file paths, symbols, commits, PR numbers, linked ticket IDs). Pass it to the investigators so they don't rediscover it. | |
| 93 | 93 | |
| 94 | 94 | ## Step 3. Spawn Parallel Investigators (default posture) |
| 95 | 95 | |
| 96 | −**Default to the full parallel investigation.** Each evidence category lives in a different kind of system, and you cannot predict from the question alone which category holds the real answer. Commit messages can lie. A ticket tracker may be silent on the question you care about, while a design doc has a crisp answer. You cannot tell which is true without looking. So look across every available category, in parallel, by default. | |
| 96 | +**Default to the full parallel investigation.** Each evidence category lives in a different kind of system, and you cannot tell from the question alone which one holds the answer without looking. So look across every available category, in parallel, by default. | |
| 97 | 97 | |
| 98 | 98 | ### Discovery |
| 99 | 99 | |
| 100 | −Before spawning investigators, list the available MCPs from the Cursor environment. Use the available-tools map when it is present. Otherwise inspect the `mcps/` directory that Cursor exposes for enabled MCP servers. | |
| 100 | +Before spawning investigators, list the available MCPs from the Cursor environment. Use the available-tools map when present. Otherwise inspect the `mcps/` directory Cursor exposes for enabled MCP servers. | |
| 101 | 101 | |
| 102 | 102 | Map each available MCP to one evidence category: |
| 103 | 103 | |
| @@ -109,54 +109,54 @@ Map each available MCP to one evidence category: · 5 unmodified lines | ||
| 109 | 109 | 6. Error / exception tracking |
| 110 | 110 | 7. Product analytics warehouse |
| 111 | 111 | |
| 112 | −Source control history is always available through git and `gh`. For the other six categories, use the MCP name, server instructions, tool names, and resource descriptors to classify the source. If an MCP could fit more than one category, choose the category that matches its primary evidence. Record ambiguous cases in the coverage map. | |
| 112 | +Source control is always available through git and `gh`. For the other six, classify using the MCP name, server instructions, tool names, and resource descriptors. If an MCP could fit more than one category, choose the one matching its primary evidence. Record ambiguous cases in the coverage map. | |
| 113 | 113 | |
| 114 | −The goal is a complete **coverage map**, not a minimal one. An investigator that searches and finds nothing is not wasted work. A null result from an issue tracker is evidence the decision was not ticketed, which is itself a useful fact about how the decision was made. Document the null, don't skip the search. | |
| 114 | +Aim for a complete **coverage map**, not a minimal one. A null result from an issue tracker is evidence the decision was not ticketed, a useful fact in itself. Document the null, don't skip the search. | |
| 115 | 115 | |
| 116 | −Launch all matching investigators in a single message so they run concurrently. The one-investigator-per-category pattern exists so each agent can specialize in one tool's query vocabulary and result shape. Don't ask one agent to cover multiple MCPs. | |
| 116 | +Launch all matching investigators in a single message so they run concurrently. One investigator per category lets each specialize in one tool's query vocabulary and result shape. Don't ask one agent to cover multiple MCPs. | |
| 117 | 117 | |
| 118 | −Subagent config (for each): | |
| 118 | +Subagent config (each): | |
| 119 | 119 | - `subagent_type`: `generalPurpose` |
| 120 | 120 | - `model`: `composer-2.5-fast` |
| 121 | −- `readonly`: `false` (agent mode). **Do not use readonly/Ask mode**. It strips MCP access, which disables MCP-backed investigators entirely. The source control investigator would technically be safe in readonly, but keep modes uniform for consistency. Investigators still shouldn't write anything. That's a posture, not a sandbox. | |
| 121 | +- `readonly`: `false` (agent mode). **Do not use readonly/Ask mode.** It strips MCP access, which disables MCP-backed investigators entirely. The source control investigator would be safe in readonly, but keep modes uniform. Investigators still shouldn't write anything. That's a posture, not a sandbox. | |
| 122 | 122 | |
| 123 | 123 | Each investigator gets: |
| 124 | 124 | 1. The base prompt from `references/investigator-prompt.md` |
| 125 | −2. The category playbook at `references/sources/<source>.md` for the selected MCP, adapted from the examples in `references/source-playbook.md` | |
| 126 | −3. The cross-cutting playbook at `references/sources/incident-postmortem.md` **if the target code looks defensive** (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers) | |
| 125 | +2. The category playbook `references/sources/<source>.md` for the selected MCP, adapted from the examples in `references/source-playbook.md` | |
| 126 | +3. The cross-cutting `references/sources/incident-postmortem.md` **if the target code looks defensive** (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers) | |
| 127 | 127 | 4. The code anchor from Step 2 (file paths, symbols, commit hashes, PR numbers, ticket IDs) |
| 128 | 128 | 5. The user's original question |
| 129 | 129 | |
| 130 | 130 | ### Investigator roster. One per available evidence category |
| 131 | 131 | |
| 132 | −Spawn one investigator per category that has a matching MCP. Each investigator owns exactly one tool or MCP. | |
| 132 | +Spawn one investigator per category that has a matching MCP. Each owns exactly one tool or MCP. | |
| 133 | 133 | |
| 134 | −Each entry below lists what the category physically contains and the shape of "why" the category is uniquely positioned to surface. Use it to know what to expect back from each investigator, how to name a gap when a category returns empty, and only in the rare provably irrelevant case, to justify a skip. Every category overlaps in coverage, but each one owns a kind of evidence the others cannot recover. That's why the default is still all seven categories with available MCPs. | |
| 134 | +Each entry lists what the category physically contains and the kind of "why" it uniquely surfaces. Use it to know what to expect back, how to name a gap when a category returns empty, and (only in the rare provably-irrelevant case) to justify a skip. Every category overlaps, but each owns a kind of evidence the others cannot recover. | |
| 135 | 135 | |
| 136 | −1. **Source control investigator**. Git history, `gh` for PRs, code comments, tests. Always spawn. The only guaranteed source. **Best at surfacing:** *implementation-time rationale captured during review*. PR descriptions stating the problem, review threads debating alternatives, inline comments encoding non-obvious constraints, test names that encode motivating edge cases, and commit messages linking tickets or incidents. This is the most trustworthy source because it's tied directly to the diff that shipped. | |
| 136 | +1. **Source control investigator**. Git history, `gh` for PRs, code comments, tests. Always spawn; the only guaranteed source. Best at surfacing *implementation-time rationale captured during review*. PR descriptions stating the problem, review threads debating alternatives, inline comments encoding non-obvious constraints, test names that encode motivating edge cases, and commit messages linking tickets or incidents. Most trustworthy because it ties directly to the diff that shipped. | |
| 137 | 137 | |
| 138 | −2. **Issue / ticket tracker investigator** (e.g. Linear, Jira, GitHub Issues, Plane, Shortcut MCP). Tickets, project docs, status updates, spec attachments. **Best at surfacing:** *the product or business forcing function*. Customer requests ("Acme needs X for their SOC2 audit"), compliance deadlines, parent-initiative framing ("Q3 enterprise readiness"), ticket-level scope changes, and labels that categorize the motivation (`customer:*`, `incident-followup`, `compliance`, `perf-regression`). Strongest when the "why" is external to engineering. | |
| 138 | +2. **Issue / ticket tracker investigator** (e.g. Linear, Jira, GitHub Issues, Plane, Shortcut MCP). Tickets, project docs, status updates, spec attachments. Best at surfacing *the product or business forcing function*. Customer requests ("Acme needs X for their SOC2 audit"), compliance deadlines, parent-initiative framing ("Q3 enterprise readiness"), ticket-level scope changes, and labels that categorize the motivation (`customer:*`, `incident-followup`, `compliance`, `perf-regression`). Strongest when the why is external to engineering. | |
| 139 | 139 | |
| 140 | −3. **Long-form documents investigator** (e.g. Notion, Confluence, Google Docs, Coda MCP). PRDs, specs, RFCs, design docs, ADRs, postmortems, team pages, meeting notes. **Best at surfacing:** *long-form design rationale*. Problem statements, explicit "alternatives considered" and "rejected approaches" sections, strategy documents that set priorities, ADRs with finalized decisions, and postmortem action items that tie directly to code. Where the "why" is written out before it becomes code. | |
| 140 | +3. **Long-form documents investigator** (e.g. Notion, Confluence, Google Docs, Coda MCP). PRDs, specs, RFCs, design docs, ADRs, postmortems, team pages, meeting notes. Best at surfacing *long-form design rationale*. Problem statements, explicit "alternatives considered" and "rejected approaches" sections, strategy documents that set priorities, ADRs with finalized decisions, and postmortem action items that tie directly to code. Where the why is written out before it becomes code. | |
| 141 | 141 | |
| 142 | −4. **Real-time team chat investigator** (e.g. Slack, Discord, Microsoft Teams, Mattermost MCP). Feature-name and symbol searches, PR URL mentions, incident channels (`#sev-*`, `#incident-*`), author-handle activity around the ship date. **Best at surfacing:** *real-time deliberation that never reached a doc*. Fire-drill decisions during incidents, Q&A between the PR author and reviewers, casual "we decided X because Y" threads, and rationale for small changes that didn't warrant a PRD. Especially important when the source control, ticket, and doc paper trail is thin. | |
| 142 | +4. **Real-time team chat investigator** (e.g. Slack, Discord, Microsoft Teams, Mattermost MCP). Feature-name and symbol searches, PR URL mentions, incident channels (`#sev-*`, `#incident-*`), author-handle activity around the ship date. Best at surfacing *real-time deliberation that never reached a doc*. Fire-drill decisions during incidents, Q&A between the PR author and reviewers, casual "we decided X because Y" threads, and rationale for small changes that didn't warrant a PRD. Especially important when the source control, ticket, and doc paper trail is thin. | |
| 143 | 143 | |
| 144 | −5. **Infrastructure observability investigator** (e.g. Datadog, New Relic, Honeycomb, Grafana, Splunk MCP). Metrics, monitors, dashboards, logs, APM traces, formal incidents. Infra/runtime view. **Best at surfacing:** *infrastructure and runtime reality that motivated the code*. Monitor thresholds whose numbers match code constants, metric spikes in the window right before a PR merge, dashboards created as postmortem action items, incident timelines that reference the target. Strongest when the target reacts to an infra signal (timeouts, retries, rate limits, circuit breakers). | |
| 144 | +5. **Infrastructure observability investigator** (e.g. Datadog, New Relic, Honeycomb, Grafana, Splunk MCP). Metrics, monitors, dashboards, logs, APM traces, formal incidents. Infra/runtime view. Best at surfacing *infrastructure and runtime reality that motivated the code*. Monitor thresholds whose numbers match code constants, metric spikes in the window right before a PR merge, dashboards created as postmortem action items, incident timelines that reference the target. Strongest when the target reacts to an infra signal (timeouts, retries, rate limits, circuit breakers). | |
| 145 | 145 | |
| 146 | −6. **Error / exception tracking investigator** (e.g. Sentry, Rollbar, Bugsnag, Airbrake MCP). Issues, events, stack traces, releases. **Best at surfacing:** *the specific exceptions and error trajectories that motivated defensive or corrective code*. Stack traces that pass through the target function, issues whose first-seen/last-seen windows bracket the PR ship date, release correlations that show an error stopping at a specific version. Strongest for catch blocks, null guards, type checks, retries, and other defenses. | |
| 146 | +6. **Error / exception tracking investigator** (e.g. Sentry, Rollbar, Bugsnag, Airbrake MCP). Issues, events, stack traces, releases. Best at surfacing *the specific exceptions and error trajectories that motivated defensive or corrective code*. Stack traces that pass through the target function, issues whose first-seen/last-seen windows bracket the PR ship date, release correlations that show an error stopping at a specific version. Strongest for catch blocks, null guards, type checks, retries, and other defenses. | |
| 147 | 147 | |
| 148 | −7. **Product analytics warehouse investigator** (e.g. Databricks, Snowflake, BigQuery, ClickHouse, dbt, Redshift MCP). Product-analytics events, experiment and feature-flag exposure tables, usage and billing events, query history, warehouse telemetry. Product/data view. Complements infrastructure observability by covering *user behavior and data reality* around the ship date rather than infra metrics. **Best at surfacing:** *product and data reality that shaped the code*. Feature-usage trajectories (a step-function ramp from zero is strong evidence that "this PR launched it"), experiment/flag exposure data tied to ship decisions, pre-ship distributions that reveal where a threshold constant came from (e.g., `limit = 128 * 1024` matching the p99 of an upload-size column), and data-pipeline scale evidence for migrations/backfills. Strongest for flag-gated code, experiment-driven ships, data migrations, and "where did this number come from" questions. | |
| 148 | +7. **Product analytics warehouse investigator** (e.g. Databricks, Snowflake, BigQuery, ClickHouse, dbt, Redshift MCP). Product-analytics events, experiment and feature-flag exposure tables, usage and billing events, query history, warehouse telemetry. Product/data view. Complements infrastructure observability by covering *user behavior and data reality* around the ship date rather than infra metrics. Best at surfacing *product and data reality that shaped the code*. Feature-usage trajectories (a step-function ramp from zero is strong evidence that this PR launched it), experiment/flag exposure data tied to ship decisions, pre-ship distributions that reveal where a threshold constant came from (e.g., `limit = 128 * 1024` matching the p99 of an upload-size column), and data-pipeline scale evidence for migrations/backfills. Strongest for flag-gated code, experiment-driven ships, data migrations, and "where did this number come from" questions. | |
| 149 | 149 | |
| 150 | 150 | ### When to skip an investigator |
| 151 | 151 | |
| 152 | −Only skip with an **explicit, written justification** that goes in the final "Sources Consulted" section. Two valid reasons to skip: | |
| 152 | +Only skip with an **explicit, written justification** that goes in the final "Sources Consulted" section. Two valid reasons: | |
| 153 | 153 | |
| 154 | −- **No MCP is available for that category in this environment**. Flag this as a gap, not a choice. Example: "Real-time team chat skipped. No matching MCP available, so conversational record was not searchable." | |
| 155 | −- **The source is provably irrelevant**, not just "probably irrelevant." A high bar. Example: "Error / exception tracking skipped. Target is a build-time script with no runtime code path." Not: "probably not in error tracking, it's a feature not an error." | |
| 154 | +- **No MCP is available for that category** in this environment. Flag this as a gap, not a choice. Example: "Real-time team chat skipped. No matching MCP available, so the conversational record was not searchable." | |
| 155 | +- **The source is provably irrelevant**, not just "probably irrelevant." A high bar. Example: "Error / exception tracking skipped. Target is a build-time script with no runtime code path." Not "probably not in error tracking, it's a feature not an error." | |
| 156 | 156 | |
| 157 | −"It's pure feature code, error tracking won't have anything" is **not** sufficient justification. Run the search, let the null result speak. "I doubt long-form docs would have this" is **not** sufficient. Check. The cost of an investigator returning empty is one subagent. The cost of missing the design doc that actually exists is a wrong answer. | |
| 157 | +"It's pure feature code, error tracking won't have anything" is **not** sufficient, and neither is "I doubt long-form docs would have this." Run the search; let the null result speak. The cost of an investigator returning empty is one subagent. The cost of missing a design doc that actually exists is a wrong answer. | |
| 158 | 158 | |
| 159 | −If your scope assessment suggests a single-commit trivial target where the PR description already contains the complete answer, you may answer inline **only after** confirming all seven available category searches would be redundant. You must say so explicitly in the output. This should be rare. | |
| 159 | +If your scope assessment suggests a single-commit trivial target where the PR description already contains the complete answer, you may answer inline **only after** confirming all seven available category searches would be redundant. Say so explicitly. This should be rare. | |
| 160 | 160 | |
| 161 | 161 | ## Step 4. Synthesize |
| 162 | 162 | |
| @@ -164,7 +164,7 @@ Spawn one synthesizer subagent: · 1 unmodified line | ||
| 164 | 164 | |
| 165 | 165 | - `subagent_type`: `generalPurpose` |
| 166 | 166 | - `model`: `claude-opus-4-8-thinking-xhigh` |
| 167 | −- `readonly`: `false` (agent mode). The synthesizer's quality check includes spot-verifying citations, which can require MCP access. Readonly/Ask mode strips MCPs and defeats that. | |
| 167 | +- `readonly`: `false` (agent mode). The synthesizer's quality check spot-verifies citations, which can require MCP access. Readonly/Ask mode strips MCPs and defeats that. | |
| 168 | 168 | |
| 169 | 169 | The synthesizer gets: |
| 170 | 170 | 1. The investigator findings, including any null results and any categories skipped with justification |
| @@ -173,11 +173,11 @@ The synthesizer gets: · 2 unmodified lines | ||
| 173 | 173 | 4. The epistemics framework from `references/epistemics.md` |
| 174 | 174 | 5. The synthesizer prompt template from `references/synthesizer-prompt.md` |
| 175 | 175 | |
| 176 | −Its job is to produce the final output: a confidence-weighted, evidence-cited narrative with clearly separated "what we know" and "what we're inferring" sections, plus honest acknowledgment of gaps and null-result sources. | |
| 176 | +Its job is the final output: a confidence-weighted, evidence-cited narrative with clearly separated "what we know" and "what we're inferring" sections, plus honest acknowledgment of gaps and null-result sources. | |
| 177 | 177 | |
| 178 | 178 | ## Step 5. Present |
| 179 | 179 | |
| 180 | −Take the synthesizer's output and present it to the user. You may lightly edit for clarity or add context from the conversation, but **do not rewrite the confidence language**. The epistemic framing is the product. Dropping the hedges to make the answer sound more authoritative is the exact failure mode this skill exists to prevent. | |
| 180 | +Take the synthesizer's output and present it to the user. You may lightly edit for clarity or add context from the conversation, but **do not rewrite the confidence language**. The epistemic framing is the product. Dropping the hedges to sound more authoritative is the exact failure mode this skill exists to prevent. | |
| 181 | 181 | |
| 182 | 182 | ## Output Format |
| 183 | 183 | |
| @@ -189,13 +189,13 @@ The final output uses this structure. Adapt as needed, but keep the confidence s · 5 unmodified lines | ||
| 189 | 189 | |
| 190 | 190 | **What We Found (direct evidence)**. Claims with explicit citations (PR #, ticket ID, doc URL, chat permalink, commit hash, code comment with file:line). Each bullet is a thing we have textual evidence for. Use present tense and quote or paraphrase the source. |
| 191 | 191 | |
| 192 | −**What We Can Reasonably Infer**. Claims that are well-supported by indirect evidence or combinations of signals, but not explicitly stated anywhere. Each bullet must explain the inference chain: "Given A and B, it's likely that C." Use hedged language ("appears to", "likely", "suggests"). | |
| 192 | +**What We Can Reasonably Infer**. Claims well-supported by indirect evidence or combinations of signals, but not explicitly stated anywhere. Each bullet must explain the inference chain: "Given A and B, it's likely that C." Use hedged language ("appears to", "likely", "suggests"). | |
| 193 | 193 | |
| 194 | −**Competing Hypotheses**. If the evidence fits multiple stories, list them. For each: the hypothesis, the evidence for it, the evidence against it. Don't force a winner when the record doesn't support one. (Skip this section if there's a clear answer.) | |
| 194 | +**Competing Hypotheses**. If the evidence fits multiple stories, list them. For each, give the hypothesis, the evidence for it, and the evidence against it. Don't force a winner when the record doesn't support one. (Skip this section if there's a clear answer.) | |
| 195 | 195 | |
| 196 | −**What We Don't Know**. Explicit gaps. Questions the user asked that the evidence didn't answer. Sources we searched and came up empty. Be specific: "We searched the issue tracker for 'rate limit' and found no ticket discussing this specific threshold" is more useful than "we don't know why." | |
| 196 | +**What We Don't Know**. Explicit gaps. Questions the user asked that the evidence didn't answer. Sources we searched and came up empty. Be specific. "We searched the issue tracker for 'rate limit' and found no ticket discussing this specific threshold" is more useful than "we don't know why." | |
| 197 | 197 | |
| 198 | −**Sources Consulted**. A bulleted list of every source, one line per investigator, including the ones that returned nothing. The reader should be able to see at a glance: (a) which MCPs were queried, (b) which came back empty, and (c) which were skipped and why. This is the coverage map. It lets the user judge investigation breadth and redirect if something obvious was missed. | |
| 198 | +**Sources Consulted**. One line per investigator, including the ones that returned nothing. The reader should see at a glance (a) which MCPs were queried, (b) which came back empty, and (c) which were skipped and why. This coverage map lets the user judge breadth and redirect if something obvious was missed. | |
| 199 | 199 | |
| 200 | 200 | Format each line as: `- <Source>: <what was searched>. <what was found, or "no relevant results," or "skipped. reason">.` |
| 201 | 201 | |
| @@ -208,22 +208,22 @@ Example: · 6 unmodified lines | ||
| 208 | 208 | - Error / exception tracking (Sentry): searched for issues first-seen in Aug 2024 with stack through `retry.ts`. Found issue SENTRY-3821 spiking in the week before the PR. |
| 209 | 209 | - Product analytics warehouse (Databricks): queried `<your_analytics_db>.<schema>.stg_backend_upstream_retry` for the 30-day window around 2024-08-14. Daily failure-classified event count fell from ~1.2k/day pre-PR to <50/day post-PR. Also checked `system.query.history` for relevant migration queries. None found. |
| 210 | 210 | |
| 211 | −After the Sources Consulted block, if the user's `why` question is a precursor to actually changing this code, convert lineage findings into a Preserve / Change / Avoid / Risk constraint set suitable for planning the change. | |
| 211 | +After the Sources Consulted block, if the user's `why` question is a precursor to actually changing this code, convert the lineage findings into a Preserve / Change / Avoid / Risk constraint set suitable for planning the change. | |
| 212 | 212 | |
| 213 | 213 | ## Common Failure Modes to Avoid |
| 214 | 214 | |
| 215 | −- **Confident storytelling**. Inventing a plausible narrative from thin evidence. If your bullet doesn't have a citation, it goes in "inferred" or "hypotheses," not "what we found." | |
| 216 | −- **Citing the code as evidence for its own intent**. "This function handles the null case because it checks for null." That's mechanics, not motivation. The motivation has to come from an external source (PR discussion, ticket, comment, conversation) or be clearly labeled as inference. | |
| 215 | +- **Confident storytelling**. A plausible narrative built from thin evidence. A bullet with no citation goes in "inferred" or "hypotheses," not "what we found." | |
| 216 | +- **Citing the code as evidence for its own intent**. "Handles the null case because it checks for null" is mechanics, not motivation. Motivation comes from an external source (PR discussion, ticket, comment, conversation) or is labeled as inference. | |
| 217 | 217 | - **Recency bias**. Assuming the most recent commit is authoritative. The current shape is often the accretion of many earlier decisions. Trace back. |
| 218 | −- **Sycophantic agreement**. If the user suggests a reason in their question ("I assume this is for performance?"), don't just confirm it. Treat it as a hypothesis and check the evidence independently. | |
| 219 | −- **Skipping the gaps section**. It's tempting to end on a strong note, but an honest accounting of what you couldn't find out is part of the value. | |
| 220 | −- **Skipping investigators by anticipation**. Deciding up front that "long-form docs probably don't have this" or "this isn't an error tracking thing" without actually searching. This is the failure mode the default-to-all-seven posture exists to prevent. A null result from a search is a data point; a skipped search is a blind spot. | |
| 221 | −- **Collapsing investigators into one agent**. Giving one subagent multiple MCPs to cover. Each MCP has its own query vocabulary, result shape, and common pitfalls. Pooling them dilutes specialization and makes it harder for the synthesizer to reason about coverage. Always one investigator per category. | |
| 218 | +- **Sycophantic agreement**. If the user suggests a reason ("I assume this is for performance?"), treat it as a hypothesis and check the evidence independently, don't just confirm it. | |
| 219 | +- **Skipping the gaps section**. An honest accounting of what you couldn't find out is part of the value. | |
| 220 | +- **Skipping investigators by anticipation**. Deciding up front that "long-form docs probably don't have this" or "this isn't an error tracking thing" without searching. The default-to-all-seven posture prevents this. A null result is a data point; a skipped search is a blind spot. | |
| 221 | +- **Collapsing investigators into one agent**. Each MCP has its own query vocabulary, result shape, and pitfalls; pooling them dilutes specialization and makes coverage harder to reason about. Always one investigator per category. | |
| 222 | 222 | |
| 223 | 223 | ## Reference Files |
| 224 | 224 | |
| 225 | 225 | - `references/epistemics.md`. Confidence tiers and phrasing guide. The synthesizer must follow it. |
| 226 | 226 | - `references/investigator-prompt.md`. Base prompt template for investigator subagents. |
| 227 | −- `references/source-playbook.md`. Index pointing at category-organized playbooks below. | |
| 228 | −- `references/sources/*.md`. One self-contained example playbook per category, plus a cross-cutting `incident-postmortem.md`. Give an investigator the single file that matches its assigned category and adapt it to the available MCP. | |
| 227 | +- `references/source-playbook.md`. Index pointing at the category playbooks below. | |
| 228 | +- `references/sources/*.md`. One self-contained example playbook per category, plus cross-cutting `incident-postmortem.md`. Give an investigator the single file that matches its category and adapt it to the available MCP. | |
| 229 | 229 | - `references/synthesizer-prompt.md`. Prompt template for the synthesizer subagent, including the output format. |
| @@ -1,16 +1,16 @@ | ||
| 1 | 1 | # Epistemics |
| 2 | 2 | |
| 3 | −This file is the heart of the `why` skill. It defines how to reason about confidence when your evidence is historical, fragmentary, and sometimes contradictory, and how to communicate that confidence to the user without flattening it into false certainty. | |
| 3 | +How to reason about confidence when evidence is historical, fragmentary, and sometimes contradictory, and how to communicate it without flattening it into false certainty. | |
| 4 | 4 | |
| 5 | −The `why` skill exists because code doesn't carry its own motivation. You can see what code does by reading it; you can't see *why it exists* by reading it. That information lives in commits, PRs, tickets, docs, and conversations, all of which are incomplete, biased, and sometimes missing entirely. Pretending otherwise produces confident-sounding guesses that mislead the user. | |
| 5 | +Code doesn't carry its own motivation. You can read what code does; you can't read *why it exists*. That lives in commits, PRs, tickets, docs, and conversations, all incomplete, biased, and sometimes missing entirely. Pretending otherwise produces confident-sounding guesses that mislead the user. | |
| 6 | 6 | |
| 7 | 7 | ## Confidence Tiers |
| 8 | 8 | |
| 9 | −Every claim in the final output must sit in one of these tiers. The tier determines both where the claim goes in the output (which section) and how it's phrased. | |
| 9 | +Every claim in the final output must sit in one of these tiers. The tier determines which output section the claim goes in and how it's phrased. | |
| 10 | 10 | |
| 11 | 11 | ### 1. Direct |
| 12 | 12 | |
| 13 | −There is an explicit, textual citation that answers the question. Not "the code does X so the author must have wanted X". Something an author actually *wrote* that says why. | |
| 13 | +An explicit, textual citation that answers the question. Not "the code does X so the author must have wanted X." Something an author actually *wrote* that says why. | |
| 14 | 14 | |
| 15 | 15 | Examples: |
| 16 | 16 | - A PR description that says "this fixes the bug where users with >1000 items couldn't paginate" |
| @@ -23,7 +23,7 @@ Phrasing: confident, present tense. "This exists because X." Cite the source. · 6 unmodified lines | ||
| 23 | 23 | |
| 24 | 24 | ### 2. Supported |
| 25 | 25 | |
| 26 | −Multiple pieces of indirect evidence converge on the same conclusion. No single source states it explicitly, but the pattern across sources makes the conclusion likely. | |
| 26 | +Multiple pieces of indirect evidence converge. No single source states it explicitly, but the pattern across sources makes it likely. | |
| 27 | 27 | |
| 28 | 28 | Examples: |
| 29 | 29 | - The PR title says "improve performance," the ticket is labeled "perf," and the surrounding commits all touch the same hot path |
| @@ -34,7 +34,7 @@ Phrasing: confident but clearly derived. "The evidence points strongly to X: [th · 4 unmodified lines | ||
| 34 | 34 | |
| 35 | 35 | ### 3. Inferred |
| 36 | 36 | |
| 37 | −The claim is a reasonable reading of the context, but nothing explicitly supports it. The reader should understand this is *your interpretation*, not a fact from the record. | |
| 37 | +A reasonable reading of the context, but nothing explicitly supports it. The reader should understand this is *your interpretation*, not a fact from the record. | |
| 38 | 38 | |
| 39 | 39 | Examples: |
| 40 | 40 | - The PR doesn't say why, but given the error was happening in production (per the incident channel timing) and the fix was rushed (merged the same day), it was likely a hotfix. |
| @@ -44,7 +44,7 @@ Phrasing: hedged. "It appears", "likely", "suggests", "is consistent with", "one · 3 unmodified lines | ||
| 44 | 44 | |
| 45 | 45 | ### 4. Speculative |
| 46 | 46 | |
| 47 | −A plausible hypothesis, but the evidence is thin and other explanations fit equally well. Presenting these is valuable. The user may know which is right, but they must be clearly marked as guesses. | |
| 47 | +A plausible hypothesis, but the evidence is thin and other explanations fit equally well. Presenting these is valuable, but mark them clearly as guesses. | |
| 48 | 48 | |
| 49 | 49 | Examples: |
| 50 | 50 | - "This might be a workaround for a browser bug that's since been fixed, but we found no contemporary evidence of that." |
| @@ -54,7 +54,7 @@ Phrasing: explicitly speculative. "One possibility is X, but we have no direct e · 3 unmodified lines | ||
| 54 | 54 | |
| 55 | 55 | ### 5. Unknown |
| 56 | 56 | |
| 57 | −You looked and couldn't find out. This is a valid and important outcome. Document it. | |
| 57 | +You looked and couldn't find out. A valid and important outcome. Document it. | |
| 58 | 58 | |
| 59 | 59 | 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." |
| 60 | 60 | |
| @@ -62,13 +62,13 @@ Phrasing: "We searched X, Y, and Z and found no evidence of why." Be specific ab · 1 unmodified line | ||
| 62 | 62 | |
| 63 | 63 | ### Words that carry confidence. Use carefully |
| 64 | 64 | |
| 65 | −These words imply **Direct** or **Supported** level confidence. Don't use them for inferences. | |
| 65 | +These imply **Direct** or **Supported** confidence. Don't use them for inferences. | |
| 66 | 66 | |
| 67 | −- "because." Implies a causal claim with evidence | |
| 68 | −- "the reason is." Same | |
| 69 | −- "was designed to." Claims author intent | |
| 70 | −- "fixes", "addresses", "solves." Claims the change achieved its goal | |
| 71 | −- "the team decided." Claims a group decision happened | |
| 67 | +- "because". Implies a causal claim with evidence | |
| 68 | +- "the reason is". Same | |
| 69 | +- "was designed to". Claims author intent | |
| 70 | +- "fixes", "addresses", "solves". Claims the change achieved its goal | |
| 71 | +- "the team decided". Claims a group decision happened | |
| 72 | 72 | |
| 73 | 73 | If you're using these, you should have a citation immediately adjacent. |
| 74 | 74 | |
| @@ -84,39 +84,39 @@ If you're using these, you should have a citation immediately adjacent. · 9 unmodified lines | ||
| 84 | 84 | - "may have been" |
| 85 | 85 | - "the evidence points toward" |
| 86 | 86 | |
| 87 | −These signal to the reader that you're interpreting, not reporting. Use them liberally in the "What We Can Reasonably Infer" section. | |
| 87 | +These signal that you're interpreting, not reporting. Use them liberally in the "What We Can Reasonably Infer" section. | |
| 88 | 88 | |
| 89 | 89 | ### Words to avoid |
| 90 | 90 | |
| 91 | −- "obviously." If it were obvious, the user wouldn't be asking | |
| 92 | −- "clearly." Almost always precedes a claim that isn't clear | |
| 93 | −- "of course." Same | |
| 91 | +- "obviously". If it were obvious, the user wouldn't be asking | |
| 92 | +- "clearly". Almost always precedes a claim that isn't clear | |
| 93 | +- "of course". Same | |
| 94 | 94 | - "just" (as in "it's just X for performance"). Dismissive and usually hides uncertainty |
| 95 | −- "I think" / "I believe." You're an agent synthesizing evidence, not giving a personal opinion. Use "the evidence suggests" instead. | |
| 95 | +- "I think" / "I believe". You're synthesizing evidence, not giving a personal opinion. Use "the evidence suggests" instead. | |
| 96 | 96 | |
| 97 | 97 | ### Avoid rationalization |
| 98 | 98 | |
| 99 | 99 | Code that "makes sense" today may have been written for reasons that no longer apply, or that were wrong when they were written. Don't retrofit a clean rationale onto messy history. |
| 100 | 100 | |
| 101 | −Specifically, resist the urge to: | |
| 101 | +Resist the urge to: | |
| 102 | 102 | - Assume the author did the "right" thing and work backward to justify it |
| 103 | 103 | - Assume a consistent pattern across the codebase was intentional when it might be copy-paste |
| 104 | 104 | - Turn an absence of evidence into evidence of absence ("no one mentioned security concerns, so it must not have been a concern") |
| 105 | 105 | |
| 106 | 106 | ## The Sycophancy Trap |
| 107 | 107 | |
| 108 | −Users often phrase `why` questions with an embedded hypothesis: "Why do we do it this way, I assume it's for performance?" Do not simply confirm the hypothesis. Treat it as one candidate explanation among others and check the evidence independently. If the evidence supports their hypothesis, say so with citations. If it doesn't, say so, and present what the evidence *does* support. | |
| 108 | +Users often phrase `why` questions with an embedded hypothesis: "Why do we do it this way, I assume it's for performance?" Don't simply confirm it. 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. | |
| 109 | 109 | |
| 110 | −This is important enough to restate. The user's guess is a prompt for investigation, not a conclusion to validate. | |
| 110 | +The user's guess is a prompt for investigation, not a conclusion to validate. | |
| 111 | 111 | |
| 112 | 112 | ## When Evidence Contradicts |
| 113 | 113 | |
| 114 | −If you find two sources that disagree (e.g., the PR description says one thing but the ticket says another), surface both in the final output. Don't pick the one that fits a tidier narrative. A typical contradiction pattern: | |
| 114 | +If two sources disagree (the PR description says one thing, the ticket says another), surface both. Don't pick the one that fits a tidier narrative. A typical pattern: | |
| 115 | 115 | |
| 116 | 116 | - **The ticket says** "we need this for customer X's compliance requirement" |
| 117 | 117 | - **The PR says** "cleaning up tech debt in this area" |
| 118 | 118 | |
| 119 | −These may both be true (the ticket motivated the work, the PR described the author's framing of it), or one may be wrong. Present both with their citations and let the user make the call. | |
| 119 | +Both may be true (the ticket motivated the work, the PR is the author's framing of it), or one may be wrong. Present both with their citations and let the user make the call. | |
| 120 | 120 | |
| 121 | 121 | ## When Evidence Is Missing |
| 122 | 122 | |
| @@ -126,7 +126,7 @@ An honest "we don't know" is one of the most valuable outputs this skill can pro · 3 unmodified lines | ||
| 126 | 126 | - They'll need to ask a human (the original author, the product owner, the team lead) to find out |
| 127 | 127 | - Or they can decide the question isn't worth pursuing further |
| 128 | 128 | |
| 129 | −Failing to mark a gap, and instead filling it with a confident guess, actively harms the user, because they'll act on the guess. | |
| 129 | +Failing to mark a gap and filling it with a confident guess actively harms the user; they'll act on the guess. | |
| 130 | 130 | |
| 131 | 131 | When you hit a gap, name it concretely: |
| 132 | 132 | - What question you were trying to answer |
| @@ -136,7 +136,7 @@ When you hit a gap, name it concretely: · 3 unmodified lines | ||
| 136 | 136 | |
| 137 | 137 | ## Calibration Check Before Finalizing |
| 138 | 138 | |
| 139 | −Before the synthesizer delivers the output, it should review every claim in "What We Found" and "What We Can Reasonably Infer" and ask: | |
| 139 | +Before delivering the output, the synthesizer should review every claim in "What We Found" and "What We Can Reasonably Infer" and ask: | |
| 140 | 140 | |
| 141 | 141 | 1. Does this claim have a citation? If not, either add one or move it to "Inferred" / "Hypotheses". |
| 142 | 142 | 2. Is the phrasing calibrated to the tier? (A Direct claim can use "because"; an Inferred claim cannot.) |
| @@ -1,25 +1,23 @@ | ||
| 1 | 1 | # Investigator Prompt Template |
| 2 | 2 | |
| 3 | −Use this template to build the prompt for each investigator subagent. Fill in the placeholders. Append the single category playbook at `sources/<source>.md` that matches this investigator's assigned evidence category (see `source-playbook.md` for the index). Also, 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 knows which incident-flavored queries to run inside its own source. | |
| 3 | +Build each investigator's prompt from this template; fill in the placeholders. Append the single category playbook `sources/<source>.md` matching this investigator's evidence category (see `source-playbook.md` for the index). 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` for the incident-flavored queries to run inside its own source. | |
| 4 | 4 | |
| 5 | 5 | --- |
| 6 | 6 | |
| 7 | −You are investigating the historical context and motivation behind a piece of code. A separate synthesizer will combine your findings with those of other investigators into a final answer, so focus on gathering evidence accurately rather than writing prose. | |
| 7 | +You are investigating the historical context and motivation behind a piece of code. A separate synthesizer combines your findings with other investigators' into a final answer, so gather evidence accurately rather than writing prose. | |
| 8 | 8 | |
| 9 | −Other investigators are searching different sources in parallel. Don't try to cover everything. Focus on your assigned source and go deep. | |
| 9 | +Other investigators search different sources in parallel. Don't try to cover everything. Focus on your assigned source and go deep. | |
| 10 | 10 | |
| 11 | 11 | ## Operating Posture |
| 12 | 12 | |
| 13 | −Work like a **careful, cautious, and precise investigator**. You are not here to produce a narrative. You are here to surface evidence and describe it accurately, including the parts that don't fit a tidy story. The more boring and exact your output looks, the more useful it is. A single verbatim quote with a precise citation is worth more than a paragraph of plausible-sounding summary. | |
| 13 | +Work like a careful, cautious, precise investigator. Don't produce a narrative; surface evidence and describe it accurately, including the parts that don't fit a tidy story. The more boring and exact your output, the more useful it is. A single verbatim quote with a precise citation beats a paragraph of plausible-sounding summary. | |
| 14 | 14 | |
| 15 | −In practice: | |
| 16 | − | |
| 17 | −- **Quote, don't paraphrase** when the exact wording matters. Citations should let the reader jump directly to the source and confirm the claim in seconds. | |
| 15 | +- **Quote, don't paraphrase** when the exact wording matters. Citations should let the reader jump to the source and confirm the claim in seconds. | |
| 18 | 16 | - **Go wide before going deep.** Cast a broad first net so you don't miss related context. Only then narrow in. |
| 19 | 17 | - **Track what you searched, not just what you found.** An absence is only useful if the reader knows what was looked for. Record queries verbatim. |
| 20 | 18 | - **Resist the story.** If three pieces of evidence line up neatly and a fourth contradicts them, the contradiction is the most interesting finding. Don't file it away. |
| 21 | −- **Consider the counterfactual.** Before reporting a finding as strong, ask: "would I expect to find this if my current reading were wrong? How would the evidence differ?" | |
| 22 | −- **Never invent.** If you're tempted to round a partial finding up into a confident statement, stop and label it as partial. A synthesizer downstream is counting on your output being accurate. | |
| 19 | +- **Consider the counterfactual.** 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. | |
| 20 | +- **Never invent.** If you're tempted to round a partial finding up into a confident statement, stop and label it partial. The synthesizer is counting on your output being accurate. | |
| 23 | 21 | |
| 24 | 22 | ## The Question |
| 25 | 23 | |
| @@ -46,23 +44,21 @@ In practice: · 20 unmodified lines | ||
| 46 | 44 | |
| 47 | 45 | ## Investigation Instructions |
| 48 | 46 | |
| 49 | −Your job is to gather **evidence**, not to answer the question directly. The synthesizer will weigh the evidence and form conclusions. | |
| 50 | − | |
| 51 | −Follow this loop: | |
| 47 | +Gather **evidence**; don't answer the question directly. The synthesizer weighs the evidence and forms conclusions. Follow this loop: | |
| 52 | 48 | |
| 53 | −1. **Cast a wide net first.** Start with broad searches so you don't miss related context. Only then narrow in on specific items. | |
| 54 | −2. **Read the whole thing.** If you find a PR, ticket, doc, or thread, read it fully. Not just the title or summary. The key evidence is often buried in a comment, a subtask, or a follow-up. | |
| 55 | −3. **Follow links within your assigned source.** If a PR references another PR or commit, pull it. If a ticket links a parent or sibling ticket, pull it. If a document links another document, pull it. Stay inside your assigned source. When you spot a cross-source reference, do NOT chase it yourself. Record it under "Additional Leads" so the investigator assigned to that other source can pick it up. The one-investigator-per-category design depends on this. Chasing cross-source links duplicates work and confuses scope. | |
| 56 | −4. **Capture quotes verbatim.** When you find evidence, record the exact text along with its location (PR number, ticket ID, URL, commit hash, file:line). The synthesizer needs to cite this precisely. | |
| 49 | +1. **Cast a wide net first.** Start broad so you don't miss related context, then narrow in on specific items. | |
| 50 | +2. **Read the whole thing.** Read any PR, ticket, doc, or thread fully, not just the title or summary. The key evidence is often buried in a comment, a subtask, or a follow-up. | |
| 51 | +3. **Follow links within your assigned source.** If a PR references another PR or commit, pull it. If a ticket links a parent or sibling, pull it. If a doc links another doc, pull it. Stay inside your assigned source. When you spot a cross-source reference, do NOT chase it yourself. Record it under "Additional Leads" so the investigator assigned to that source can pick it up. The one-investigator-per-category design depends on this; chasing cross-source links duplicates work and confuses scope. | |
| 52 | +4. **Capture quotes verbatim** with their location (PR number, ticket ID, URL, commit hash, file:line). The synthesizer needs to cite this precisely. | |
| 57 | 53 | 5. **Note absences.** If you searched for something and came up empty, that's also a finding. Record what you searched for and what you didn't find. |
| 58 | −6. **Watch for contradictions.** If two items in your source disagree with each other, record both. Don't suppress the inconvenient one. | |
| 54 | +6. **Watch for contradictions.** If two items in your source disagree, record both. Don't suppress the inconvenient one. | |
| 59 | 55 | |
| 60 | −Don't try to synthesize. Don't form a final opinion on "the why." Your job is to collect the raw material honestly and completely. The synthesizer will do the reasoning. | |
| 56 | +Don't synthesize or form a final opinion on "the why." Collect the raw material honestly and completely; the synthesizer does the reasoning. | |
| 61 | 57 | |
| 62 | 58 | ## Epistemic Discipline |
| 63 | 59 | |
| 64 | −- **Don't confuse mechanics with motivation.** If a commit *changes* a line from `limit = 50` to `limit = 100`, the commit shows the change. It doesn't necessarily explain why. Look for the explanation in the commit message, PR description, linked ticket, or review comments. | |
| 65 | −- **Don't infer intent from code style.** "The author chose a functional approach" is an observation about code, not evidence of intent. Only claim intent when the author stated intent. | |
| 60 | +- **Don't confuse mechanics with motivation.** A commit changing `limit = 50` to `limit = 100` shows the change, not necessarily why. Look for the explanation in the commit message, PR description, linked ticket, or review comments. | |
| 61 | +- **Don't infer intent from code style.** "The author chose a functional approach" is an observation about code, not evidence of intent. Claim intent only when the author stated it. | |
| 66 | 62 | - **Preserve uncertainty.** If the evidence is ambiguous, say so. If one reading is more plausible but not certain, say that. Don't collapse ambiguity to look decisive. |
| 67 | 63 | - **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. |
| 68 | 64 | |
| @@ -74,10 +70,10 @@ Return your findings in this structure. The synthesizer will read it directly. · 5 unmodified lines | ||
| 74 | 70 | 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.). |
| 75 | 71 | |
| 76 | 72 | ### What I Searched |
| 77 | −Enumerate the queries you ran, the items you opened, the places you looked. Be specific. This is what tells the synthesizer how thorough the investigation was and what might still be unsearched. | |
| 73 | +The queries you ran, the items you opened, the places you looked. Be specific. This tells the synthesizer how thorough the investigation was and what might still be unsearched. | |
| 78 | 74 | |
| 79 | 75 | ### Direct Evidence Found |
| 80 | −For each piece of direct evidence (something that explicitly addresses the question), give: | |
| 76 | +For each piece that explicitly addresses the question: | |
| 81 | 77 | - **What it says**: verbatim quote or accurate paraphrase |
| 82 | 78 | - **Where it's from**: PR #123, ticket ID, doc URL, chat permalink, commit hash, or file:line |
| 83 | 79 | - **Author and date** (if available) |
| @@ -91,17 +87,17 @@ Items that don't explicitly answer the question but bear on it. For each: · 7 unmodified lines | ||
| 91 | 87 | - **Alternative readings**: if the same evidence could support a different interpretation, note it |
| 92 | 88 | |
| 93 | 89 | ### Contradictions |
| 94 | −If you found two items that disagree with each other, list them here with both citations. | |
| 90 | +Two items that disagree with each other, with both citations. | |
| 95 | 91 | |
| 96 | 92 | ### Gaps |
| 97 | 93 | What you searched for and didn't find. Be specific: "Searched the issue tracker for [query] across [time range]. No matching issues." These absences are valuable data. |
| 98 | 94 | |
| 99 | 95 | ### Additional Leads |
| 100 | −Anything that suggests further investigation in a different source. For example, if a PR references a chat thread that wasn't in your source, note the reference so the real-time team chat investigator or a follow-up pass can pursue it. | |
| 96 | +Anything that suggests further investigation in a different source. For example, if a PR references a chat thread that wasn't in your source, note it so the real-time team chat investigator or a follow-up pass can pursue it. | |
| 101 | 97 | |
| 102 | 98 | ## What You're Not Doing |
| 103 | 99 | |
| 104 | 100 | - Writing the final answer. The synthesizer does that. |
| 105 | 101 | - Picking sides in contradictions. Surface them. |
| 106 | −- Speculating beyond what the evidence supports. If you have a hunch but no evidence, don't present it as evidence. | |
| 107 | −- Reading the code itself to figure out intent. You may read the code to understand what the target *is*, but don't confuse "this is what the code does" with "this is why." | |
| 102 | +- Speculating beyond what the evidence supports. A hunch with no evidence isn't evidence. | |
| 103 | +- Reading the code itself to figure out intent. You may read the code to understand what the target *is*, but don't confuse "what the code does" with "why." | |
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | # Source playbooks |
| 2 | 2 | |
| 3 | −The why skill spawns one investigator per available evidence category. Each investigator reads a single source-specific playbook below. The playbooks are concrete examples for common MCPs. Adapt them when you have a different MCP in the same category. | |
| 3 | +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. | |
| 4 | 4 | |
| 5 | 5 | | Category | Playbook | Example MCP it documents | |
| 6 | 6 | |---|---|---| |
| @@ -6,22 +6,22 @@ · 5 unmodified lines | ||
| 6 | 6 | - PR descriptions, review comments, and discussion threads (via `gh`) |
| 7 | 7 | - Inline code comments, TODOs, FIXMEs, deprecation notes |
| 8 | 8 | - ADRs (architectural decision records) if the repo keeps them |
| 9 | −- Tests. Test names and assertions often encode the edge cases that motivated a change | |
| 9 | +- Tests. Names and assertions often encode the edge cases that motivated a change | |
| 10 | 10 | - Related files modified in the same commits (co-change signal) |
| 11 | 11 | - CHANGELOG entries, release notes in the repo |
| 12 | 12 | - Issue/ticket IDs mentioned in commit messages and PR bodies |
| 13 | 13 | |
| 14 | −This is the most trustworthy source because it's tied directly to the code. It's also the most complete. Everything that went through the repo should be here. | |
| 14 | +The most trustworthy source, tied directly to the code, and the most complete. Everything that went through the repo should be here. | |
| 15 | 15 | |
| 16 | 16 | ## How to search it |
| 17 | 17 | |
| 18 | −Start by expanding the seed commit list: | |
| 18 | +Expand the seed commit list: | |
| 19 | 19 | |
| 20 | 20 | ```bash |
| 21 | 21 | # Full history of the file through renames |
| 22 | 22 | git log --follow --oneline -- <file> |
| 23 | 23 | |
| 24 | −# Commits that touched the specific lines (pickaxe, finds commits that added or removed this exact text) | |
| 24 | +# Pickaxe: commits that added or removed this exact text | |
| 25 | 25 | git log -S '<exact_string_from_code>' -- <file> |
| 26 | 26 | |
| 27 | 27 | # Or for patterns: |
| @@ -37,7 +37,7 @@ git show <hash> · 9 unmodified lines | ||
| 37 | 37 | git log <old>..<new> -p -- <file> |
| 38 | 38 | ``` |
| 39 | 39 | |
| 40 | −Then for each commit that looks substantive, pull the PR context: | |
| 40 | +For each substantive commit, pull the PR context: | |
| 41 | 41 | |
| 42 | 42 | ```bash |
| 43 | 43 | # Find the PR number from the merge commit or branch |
| @@ -46,10 +46,10 @@ git log -1 --format=%B <hash> · 2 unmodified lines | ||
| 46 | 46 | # Full PR context: body, review comments, linked issues |
| 47 | 47 | gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews,files |
| 48 | 48 | |
| 49 | −# If the PR has discussion, the --json reviews and comments fields are where the real signal is | |
| 49 | +# The --json reviews and comments fields are where the real signal is | |
| 50 | 50 | ``` |
| 51 | 51 | |
| 52 | −Look in the repo for out-of-band docs: | |
| 52 | +Look for out-of-band docs: | |
| 53 | 53 | |
| 54 | 54 | ```bash |
| 55 | 55 | # ADRs often live in docs/adr/ or similar |
| @@ -58,7 +58,7 @@ rg -l -i 'architecture.decision' --glob '*.md' · 2 unmodified lines | ||
| 58 | 58 | # TODOs and FIXMEs near the target |
| 59 | 59 | rg -n -C2 '(TODO|FIXME|HACK|XXX|NOTE)' <target_file> |
| 60 | 60 | |
| 61 | −# Related tests. Test names often encode the "why" | |
| 61 | +# Related tests. Names often encode the "why" | |
| 62 | 62 | rg -l '<symbol>' --glob '*test*' |
| 63 | 63 | ``` |
| 64 | 64 | |
| @@ -74,8 +74,8 @@ rg -l '<symbol>' --glob '*test*' · 9 unmodified lines | ||
| 74 | 74 | ## Common pitfalls |
| 75 | 75 | |
| 76 | 76 | - **Squash-merge flatlands.** If the repo squashes PRs, individual commits in the branch history are lost. Fall back to PR body and comments. |
| 77 | −- **Misleading commit messages.** "Small refactor" sometimes hides intentional behavior change. Look at the diff, not just the message. | |
| 78 | −- **Cargo-culted patterns.** The author may have copied a pattern from elsewhere without understanding why. Check if the pattern originated earlier in the codebase and investigate *that* commit. | |
| 77 | +- **Misleading commit messages.** "Small refactor" sometimes hides an intentional behavior change. Look at the diff, not the message. | |
| 78 | +- **Cargo-culted patterns.** The author may have copied a pattern without understanding why. Check if the pattern originated earlier in the codebase and investigate *that* commit. | |
| 79 | 79 | - **Bot commits and auto-merges.** Dependabot, Renovate, and automated backports usually don't carry motivation. Skip them when trying to find intent. |
| 80 | 80 | - **Treating code as evidence of intent.** The code itself isn't evidence for why it exists. Evidence comes from commit messages, PRs, comments, tests, docs. Don't cite "the function is named X" as evidence of intent. |
| 81 | 81 | |
| @@ -2,12 +2,10 @@ · 1 unmodified line | ||
| 2 | 2 | |
| 3 | 3 | ## What this source contains |
| 4 | 4 | |
| 5 | −Databricks is the product-analytics, data-pipeline, and warehouse-telemetry layer. It complements Datadog: Datadog is the *infra/runtime* view; Databricks is the *product/data* view, what users actually did, which experiments ran, how feature usage evolved, where a threshold constant came from. | |
| 5 | +Databricks is the product-analytics, data-pipeline, and warehouse-telemetry layer. It complements Datadog: Datadog is the *infra/runtime* view, Databricks is the *product/data* view (what users did, which experiments ran, how feature usage evolved, where a threshold constant came from). | |
| 6 | 6 | |
| 7 | −Relevant content: | |
| 8 | − | |
| 9 | −- **Product analytics events.** `your_warehouse.events.analytics_track_event` (raw) and the typed, deduplicated per-event dbt models in `<your_analytics_db>.<schema>.<table>`. User behavior: feature invocations, clicks, accepts/rejects, submissions, client-reported errors. | |
| 10 | −- **Usage & billing events.** `your_warehouse.events.usage_event` / `<your_analytics_db>.<schema>.stg_usage_events`; `your_warehouse.events.raw_model_event` / `<your_analytics_db>.<schema>.stg_raw_model_events`. Relevant for cost- or volume-driven decisions. | |
| 7 | +- **Product analytics events.** `your_warehouse.events.analytics_track_event` (raw) and typed, deduplicated per-event dbt models in `<your_analytics_db>.<schema>.<table>`. User behavior: feature invocations, clicks, accepts/rejects, submissions, client-reported errors. | |
| 8 | +- **Usage & billing events.** `your_warehouse.events.usage_event` / `<your_analytics_db>.<schema>.stg_usage_events`; `your_warehouse.events.raw_model_event` / `<your_analytics_db>.<schema>.stg_raw_model_events`. For cost- or volume-driven decisions. | |
| 11 | 9 | - **Experiment / feature-flag data.** Exposure and outcome tables. **Schema is company-specific.** Probe with `SHOW TABLES` before assuming names. |
| 12 | 10 | - **System tables.** `system.query.history`, `system.compute.warehouses`, `system.billing.*`, `system.access.audit`. Answer "was this query expensive?", "how often did anyone run this?", "when did warehouse load spike?" |
| 13 | 11 | - **dbt lineage.** Models in `<your_analytics_db>.<schema>` reveal what pipelines depend on a table/field; upstream changes frequently motivate consumer-code changes. |
| @@ -15,7 +13,7 @@ Relevant content: · 1 unmodified line | ||
| 15 | 13 | |
| 16 | 14 | ## How to search it |
| 17 | 15 | |
| 18 | −Use the Databricks SQL MCP available in your environment. Primary tool: `execute_sql_read_only`. If it returns a `statement_id`, poll with `poll_sql_result` rather than re-running. | |
| 16 | +Use the Databricks SQL MCP. Primary tool: `execute_sql_read_only`. If it returns a `statement_id`, poll with `poll_sql_result` rather than re-running. | |
| 19 | 17 | |
| 20 | 18 | **Orient before querying.** Schemas are company-specific; probe before trusting a table name: |
| 21 | 19 | |
| @@ -26,9 +24,9 @@ DESCRIBE TABLE <your_analytics_db>.<schema>.stg_<event>; · 4 unmodified lines | ||
| 26 | 24 | |
| 27 | 25 | **Time-bound every query.** These tables are huge and unconstrained scans time out. Filter on `_timestamp` (events) or `start_time` (`system.query.history`) with a window bracketing the ship date, typically ~30 days before and after, wider only for strong reason. |
| 28 | 26 | |
| 29 | −**Prefer typed dbt models over the raw table.** `<your_analytics_db>.<schema>.<table>` is deduplicated, typed, and liquid-clustered; `your_warehouse.events.analytics_track_event` has duplicates and untyped `properties_json`. Model-name pattern: `stg_<source>_<event_name_with_underscores>` where `<source>` is `app`, `backend`, `website`, or `cli`. See the `databricks-use-dbt-models` skill for the full mapping. Drop to the raw table only when there's no dbt model yet, or you need events from inside the dbt refresh lag. | |
| 27 | +**Prefer typed dbt models over the raw table.** `<your_analytics_db>.<schema>.<table>` is deduplicated, typed, and liquid-clustered; `your_warehouse.events.analytics_track_event` has duplicates and untyped `properties_json`. Model-name pattern: `stg_<source>_<event_name_with_underscores>`, where `<source>` is `app`, `backend`, `website`, or `cli`. See the `databricks-use-dbt-models` skill for the full mapping. Drop to the raw table only when there's no dbt model yet, or you need events from inside the dbt refresh lag. | |
| 30 | 28 | |
| 31 | −**Column conventions on the typed dbt models** (knowing these avoids a round-trip through `DESCRIBE`): | |
| 29 | +**Column conventions on the typed dbt models** (knowing these avoids a `DESCRIBE` round-trip): | |
| 32 | 30 | |
| 33 | 31 | - `_timestamp`, `_id`, `_auth_id`, `_request_id`, `event_name`. Standard on every model |
| 34 | 32 | - `properties_<name>`. Typed, underscore-cased event properties (`properties_entrypoint`, `properties_size_bytes`, …) |
| @@ -36,9 +34,9 @@ DESCRIBE TABLE <your_analytics_db>.<schema>.stg_<event>; · 1 unmodified line | ||
| 36 | 34 | |
| 37 | 35 | ### Investigation patterns that tend to pay off |
| 38 | 36 | |
| 39 | −You already know SQL; these just point at which table + column combinations carry which shape of "why". Pick the one that matches the target: | |
| 37 | +Pick the table + column combination that matches the target: | |
| 40 | 38 | |
| 41 | −1. **Event usage trajectory.** Daily counts on the relevant `stg_*` model across a ±30d window around the PR merge. A step function from zero to steady volume within a day or two of the merge is strong circumstantial evidence that the PR launched the feature. A decay to zero suggests a deprecation or deletion motive. | |
| 39 | +1. **Event usage trajectory.** Daily counts on the relevant `stg_*` model across a ±30d window around the PR merge. A step function from zero to steady volume within a day or two of the merge is strong circumstantial evidence the PR launched the feature. A decay to zero suggests a deprecation or deletion. | |
| 42 | 40 | 2. **Guard-rail / defensive-check origin.** Distribution (median / p99 / max) of the relevant `properties_<name>` column in the 14 days *before* the PR. A p99 that matches the target's threshold constant suggests the number was chosen from data. |
| 43 | 41 | 3. **Experiment / feature-flag lookup.** `SHOW TABLES ... LIKE '*experiment*'` to find the exposure table, then pull exposure counts by variant for the relevant flag key near the PR date. |
| 44 | 42 | 4. **Query-history evidence for migrations, backfills, or perf rewrites.** `system.query.history` filtered by `statement_text ILIKE '%<table_or_symbol>%'` with a tight `start_time` window surfaces the expensive queries that likely motivated the change (sort by `total_duration_ms` or aggregate `SUM(read_bytes)`, `COUNT(*)`). |
| @@ -46,16 +44,14 @@ You already know SQL; these just point at which table + column combinations carr · 1 unmodified line | ||
| 46 | 44 | |
| 47 | 45 | ## What good evidence looks like here |
| 48 | 46 | |
| 49 | −- An event's daily count goes from ~0 to steady volume within a day or two of the PR merge. Suggests "this PR launched the feature" | |
| 47 | +Beyond the pattern shapes above: | |
| 48 | + | |
| 50 | 49 | - An error-classifying event's count drops to near zero in the days after a defensive-code PR. Suggests the PR resolved that error class |
| 51 | 50 | - An exposure table row names the target's feature-flag key with a "shipped" / "concluded" decision around the PR ship date |
| 52 | −- A pre-ship distribution whose p99 matches the target's threshold constant. Suggests the number was chosen from data, not plucked from the air | |
| 53 | −- A `system.query.history` row shows a heavy migration/backfill query running around the same day a PR changed the target schema | |
| 54 | −- A `<your_analytics_db>.<schema>` model the target depends on was changed upstream in the same window (lead for the git investigator) | |
| 55 | 51 | |
| 56 | 52 | ## Common pitfalls |
| 57 | 53 | |
| 58 | −- **Instrumented ≠ caused.** The existence of an event means someone cared enough to log it, not that the target code exists *because* of it. Always pair with a PR/commit citation from the git investigator before claiming causation. | |
| 54 | +- **Instrumented ≠ caused.** An event's existence means someone cared enough to log it, not that the target code exists *because* of it. Pair with a PR/commit citation from the git investigator before claiming causation. | |
| 59 | 55 | - **Silent instrumentation changes.** A step function in event volume may mean a new event started being logged, not that user behavior changed. Check for instrumentation PRs in the same window before reading the ramp as a feature-launch signal. |
| 60 | 56 | - **Schema drift.** Event properties evolve; a column on the typed dbt model today may not have existed when the target was written. Older data may carry the property only inside raw `properties_json`. |
| 61 | 57 | - **dbt refresh lag.** `<your_analytics_db>.<schema>.*` is rebuilt on a schedule (often hourly/daily). For events from the last few hours, fall back to `your_warehouse.events.*` and deduplicate by `_id`. |
| @@ -2,23 +2,23 @@ · 1 unmodified line | ||
| 2 | 2 | |
| 3 | 3 | ## What this source contains |
| 4 | 4 | |
| 5 | −Datadog holds the runtime record of the system, what actually happened in production, as opposed to what was planned or discussed. For "why" questions, the useful layers are: | |
| 5 | +Datadog holds the runtime record: what actually happened in production, as opposed to what was planned or discussed. | |
| 6 | 6 | |
| 7 | −- **Metrics.** Counters, gauges, histograms instrumented by the team. The *presence* of a metric is itself evidence: someone thought this number was worth watching. | |
| 8 | −- **Monitors & alerts.** The conditions the team decided warranted waking someone up. A monitor that fires on `rate_limit_hit > 10/min` is direct evidence the team worried about that threshold. | |
| 9 | −- **Dashboards.** Curated views. The charts on a dashboard tell you what the team considers important for a subsystem. | |
| 10 | −- **APM traces & spans.** Request-level runtime data. Useful for "why is this function slow" / "why is there a timeout here" questions. | |
| 11 | −- **Logs.** High-volume event records. Often contain error conditions that motivated defensive code. | |
| 12 | −- **Incidents.** Formal incident records with timelines and postmortems linked. | |
| 13 | −- **Notebooks.** Exploratory investigations the team has done; often contain hypotheses and analyses. | |
| 7 | +- **Metrics.** Counters, gauges, histograms instrumented by the team. A metric's *presence* is itself evidence: someone thought this number worth watching. | |
| 8 | +- **Monitors & alerts.** Conditions the team decided warranted waking someone up. A monitor firing on `rate_limit_hit > 10/min` is direct evidence the team worried about that threshold. | |
| 9 | +- **Dashboards.** Curated views. The charts tell you what the team considers important for a subsystem. | |
| 10 | +- **APM traces & spans.** Request-level runtime data. Useful for "why is this slow" / "why is there a timeout here" questions. | |
| 11 | +- **Logs.** High-volume event records. Often contain the error conditions that motivated defensive code. | |
| 12 | +- **Incidents.** Formal incident records with timelines and linked postmortems. | |
| 13 | +- **Notebooks.** Exploratory investigations; often contain hypotheses and analyses. | |
| 14 | 14 | |
| 15 | −Datadog evidence answers "what was the production reality around the time this code was written?", which often explains why the code has its particular shape. | |
| 15 | +Datadog answers "what was the production reality around the time this code was written?", which often explains the code's shape. | |
| 16 | 16 | |
| 17 | 17 | ## How to search it |
| 18 | 18 | |
| 19 | −Use the Datadog MCP available in your environment. Start broad, then narrow. | |
| 19 | +Use the Datadog MCP. Start broad, then narrow. | |
| 20 | 20 | |
| 21 | −1. **Context about the owning service.** Before diving in, identify which service(s) the target code belongs to: | |
| 21 | +1. **Identify the owning service(s).** | |
| 22 | 22 | |
| 23 | 23 | ``` |
| 24 | 24 | search_datadog_services (filter by name or team) |
| @@ -32,36 +32,36 @@ Use the Datadog MCP available in your environment. Start broad, then narrow. · 7 unmodified lines | ||
| 32 | 32 | search_datadog_monitors (same queries) |
| 33 | 33 | ``` |
| 34 | 34 | |
| 35 | − When you find a dashboard or monitor that covers the target, note the queries it runs and the thresholds it watches. The threshold itself is frequently the answer to a "why is this clamped at N?" question. | |
| 35 | + When a dashboard or monitor covers the target, note its queries and watched thresholds. The threshold is frequently the answer to "why is this clamped at N?" | |
| 36 | 36 | |
| 37 | 37 | 3. **Metrics around the target.** |
| 38 | 38 | |
| 39 | 39 | ``` |
| 40 | 40 | search_datadog_metrics (by name pattern, e.g., the feature or symbol) |
| 41 | − get_datadog_metric_context (for metadata: description, units, tags) | |
| 42 | − get_datadog_metric (timeseries, useful for "was there a spike around the PR date?") | |
| 41 | + get_datadog_metric_context (metadata: description, units, tags) | |
| 42 | + get_datadog_metric (timeseries; "was there a spike around the PR date?") | |
| 43 | 43 | ``` |
| 44 | 44 | |
| 45 | − If you can correlate a metric's trajectory with when the target code was added or changed, that's strong supporting evidence: "the `payment_timeout` metric shows a spike on 2023-11-03, and the retry logic was merged 2023-11-06." | |
| 45 | + Correlating a metric's trajectory with the target's add/change date is strong supporting evidence: "the `payment_timeout` metric spiked 2023-11-03, and the retry logic merged 2023-11-06." | |
| 46 | 46 | |
| 47 | 47 | 4. **Logs. Narrow, don't dump.** |
| 48 | 48 | |
| 49 | 49 | ``` |
| 50 | − search_datadog_logs (look at raw log patterns near the target, set use_log_patterns=true) | |
| 50 | + search_datadog_logs (raw log patterns near the target, set use_log_patterns=true) | |
| 51 | 51 | analyze_datadog_logs (SQL-style aggregations, only when you need counts) |
| 52 | 52 | ``` |
| 53 | 53 | |
| 54 | − Search with symbols, error strings, or feature names. **Strongly prefer time-bounded queries** scoped to a window around the change (e.g., 30 days before/after). Datadog log volume is huge and unconstrained searches waste time and may time out. | |
| 54 | + Search with symbols, error strings, or feature names. **Strongly prefer time-bounded queries** (e.g., 30 days before/after the change). Log volume is huge; unconstrained searches waste time and may time out. | |
| 55 | 55 | |
| 56 | 56 | 5. **APM spans and traces.** |
| 57 | 57 | |
| 58 | 58 | ``` |
| 59 | − aggregate_spans (for stats: "how often does this endpoint fail?") | |
| 60 | − search_datadog_spans (for inspecting individual spans) | |
| 61 | − get_datadog_trace (for a specific trace ID) | |
| 59 | + aggregate_spans (stats: "how often does this endpoint fail?") | |
| 60 | + search_datadog_spans (inspect individual spans) | |
| 61 | + get_datadog_trace (a specific trace ID) | |
| 62 | 62 | ``` |
| 63 | 63 | |
| 64 | − Useful for questions about timeouts, retries, slow paths, and cross-service behavior. | |
| 64 | + Useful for timeouts, retries, slow paths, and cross-service behavior. | |
| 65 | 65 | |
| 66 | 66 | 6. **Incidents.** |
| 67 | 67 | |
| @@ -70,23 +70,23 @@ Use the Datadog MCP available in your environment. Start broad, then narrow. · 2 unmodified lines | ||
| 70 | 70 | get_datadog_incident (full detail for a specific incident) |
| 71 | 71 | ``` |
| 72 | 72 | |
| 73 | − If the target code looks defensive, search for incidents around the time it was added. An incident whose timeline includes "added defensive check for X" is near-direct evidence. | |
| 73 | + If the target looks defensive, search for incidents around the time it was added. An incident whose timeline includes "added defensive check for X" is near-direct evidence. | |
| 74 | 74 | |
| 75 | 75 | ## What good evidence looks like here |
| 76 | 76 | |
| 77 | −- A monitor whose query and threshold match the exact constraint the code enforces (e.g., code clamps to 100; monitor alerts when requests exceed 100/min) | |
| 77 | +- A monitor whose query and threshold match the constraint the code enforces (code clamps to 100; monitor alerts when requests exceed 100/min) | |
| 78 | 78 | - A dashboard created by the target's author, with widgets that correspond to what the code measures or guards against |
| 79 | −- A metric that shows a production spike immediately before the code was merged, and stable values after | |
| 80 | −- An incident record that references the target code, the same symbols, or the same error strings | |
| 81 | −- Logs showing a specific error pattern that the defensive code would prevent, timestamped in the window before the change | |
| 79 | +- A metric showing a production spike immediately before the code was merged, and stable values after | |
| 80 | +- An incident record referencing the target code, the same symbols, or the same error strings | |
| 81 | +- Logs showing a specific error pattern the defensive code would prevent, timestamped in the window before the change | |
| 82 | 82 | |
| 83 | 83 | ## Common pitfalls |
| 84 | 84 | |
| 85 | −- **Correlation is not causation.** A metric spike before a PR and stabilization after is suggestive but not definitive. Other changes may have landed in the same window. Always check neighboring PRs. | |
| 86 | −- **Overfitting to the chart you found.** Datadog visualizations are *made* by humans and reflect that human's framing. A chart named "retry success rate" is evidence the team cared about retry success, not necessarily that it's why a specific line of code exists. | |
| 85 | +- **Correlation is not causation.** A spike before a PR and stabilization after is suggestive, not definitive. Other changes may have landed in the same window. Check neighboring PRs. | |
| 86 | +- **Overfitting to the chart you found.** Datadog visualizations are *made* by humans and reflect that human's framing. A chart named "retry success rate" is evidence the team cared about retry success, not that it's why a specific line of code exists. | |
| 87 | 87 | - **Vanished telemetry.** Metrics can be renamed, deleted, or have short retention. If you can't find data from the relevant window, that's a gap, not a null result. |
| 88 | −- **Noise at scale.** Searching logs for a common string will return thousands of matches. Narrow by service, tag, and time window aggressively. Use `analyze_datadog_logs` to aggregate rather than dumping raw logs. | |
| 89 | −- **Instrumented != caused.** The existence of a metric tells you someone cared enough to measure something. It doesn't tell you that the code you're investigating was added *because* of the metric. Cross-reference with commit/PR dates. | |
| 88 | +- **Noise at scale.** Searching logs for a common string returns thousands of matches. Narrow by service, tag, and time aggressively. Use `analyze_datadog_logs` to aggregate rather than dumping raw logs. | |
| 89 | +- **Instrumented != caused.** A metric's existence tells you someone cared enough to measure something, not that the code was added *because* of it. Cross-reference with commit/PR dates. | |
| 90 | 90 | |
| 91 | 91 | ## What to return |
| 92 | 92 | |
| @@ -1,15 +1,15 @@ | ||
| 1 | 1 | # Incident & Postmortem Context |
| 2 | 2 | |
| 3 | −This isn't a separate source. It's a **cross-cutting angle**. Incidents often motivate defensive code ("we added this check after the X outage"), so if the target looks defensive (null checks, retry logic, timeout handling, rate limiting, feature flags), specifically hunt for incident history across every available source: | |
| 3 | +Not a separate source, a **cross-cutting angle**. Incidents often motivate defensive code ("we added this check after the X outage"), so if the target looks defensive (null checks, retry logic, timeout handling, rate limiting, feature flags), specifically hunt for incident history across every available source: | |
| 4 | 4 | |
| 5 | 5 | - **Notion**: search for postmortems mentioning the target file, feature, or error string |
| 6 | 6 | - **Linear**: look for tickets labeled `incident`, `sev-*`, `postmortem-action-item`, `reliability` |
| 7 | 7 | - **Slack**: search `#sev-*` and `#incident-*` channels around the dates the target code was added |
| 8 | −- **Git**: commits with messages like "fix for incident", "add defensive check", "revert" followed by a "re-apply with..." are strong signals | |
| 8 | +- **Git**: commits with messages like "fix for incident", "add defensive check", "revert" followed by "re-apply with..." are strong signals | |
| 9 | 9 | - **Datadog**: `search_datadog_incidents` for formal incident records with timelines; dashboards and monitors created as postmortem action items |
| 10 | 10 | - **Sentry**: issues whose first-seen/last-seen window aligns with the target's PR ship date; stack traces through the target |
| 11 | 11 | - **Databricks**: product-analytics events that classify an error condition (client-reported failures, user-visible retry events, etc.) often spike during an incident window. A drop in that event count after the target PR ships is circumstantial support that the target code resolved the user-visible symptom, even when Datadog/Sentry signal is noisy. |
| 12 | 12 | |
| 13 | 13 | If you find an incident link, fetch the full postmortem. Postmortems typically have an "Action Items" section that ties directly to code changes. When multiple sources corroborate (a Datadog incident ID appears in a Linear ticket, which appears in a Notion postmortem, which appears in a Slack thread that links to the target PR, and the Databricks error-event count drops after the fix), the evidence is especially strong. |
| 14 | 14 | |
| 15 | −This angle is worth spending time on when the defensive character of the code makes an incident-driven origin plausible. Skip it for code that doesn't look defensive. | |
| 15 | +Worth spending time on when the code's defensive character makes an incident-driven origin plausible. Skip it for code that doesn't look defensive. | |
| @@ -3,35 +3,29 @@ · 2 unmodified lines | ||
| 3 | 3 | ## What this source contains |
| 4 | 4 | |
| 5 | 5 | - Issues describing features, bugs, and their motivation |
| 6 | −- Project docs attached to issues (often contain PRDs or specs) | |
| 6 | +- Project docs attached to issues (often PRDs or specs) | |
| 7 | 7 | - Parent/sub-issue relationships (broader initiative → specific tickets) |
| 8 | −- Comments on issues (often contain clarifications, changes of scope, "why we're doing this" rationale) | |
| 8 | +- Comments on issues (clarifications, scope changes, "why we're doing this" rationale) | |
| 9 | 9 | - Labels (e.g., `compliance`, `customer-request`, `perf`) that signal the type of motivation |
| 10 | 10 | - Status updates that explain scope changes |
| 11 | 11 | - Attachments and linked GitHub PRs |
| 12 | 12 | |
| 13 | −Linear is often where the product/business context lives, the "we're doing this because customer X asked" or "this is for the Q3 compliance initiative" layer. | |
| 13 | +Linear is where the product/business context often lives: the "we're doing this because customer X asked" or "this is for the Q3 compliance initiative" layer. | |
| 14 | 14 | |
| 15 | 15 | ## How to search it |
| 16 | 16 | |
| 17 | −Use the Linear MCP available in your environment. | |
| 18 | − | |
| 19 | −Good queries: | |
| 17 | +Use the Linear MCP. | |
| 20 | 18 | |
| 21 | 19 | 1. **Start with linked tickets.** If the seed commits or PRs reference ticket IDs (e.g., `ENG-1234`, `[BUG-567]`), fetch those first with `get_issue`. Read the full issue including comments. |
| 22 | − | |
| 23 | 20 | 2. **List related issues by keyword.** Use `list_issues` with text search for the feature name, key symbol, or business term. Try multiple phrasings. |
| 24 | − | |
| 25 | −3. **Walk the issue tree.** If you land on a sub-issue, fetch its parent. Sub-issues are usually tactical; parents often carry the "why." | |
| 26 | − | |
| 27 | −4. **Read project docs.** If the issue belongs to a project, use `get_project` and check for attached docs. Project-level documents are where specs and rationale are most often captured. | |
| 28 | − | |
| 29 | −5. **Check labels and milestones.** Labels often hint at category of motivation (customer-request, incident-followup, compliance). Milestones tie work to deadlines which themselves often reveal motivation. | |
| 21 | +3. **Walk the issue tree.** If you land on a sub-issue, fetch its parent. Sub-issues are tactical; parents often carry the "why." | |
| 22 | +4. **Read project docs.** If the issue belongs to a project, use `get_project` and check attached docs. Project-level documents are where specs and rationale are most often captured. | |
| 23 | +5. **Check labels and milestones.** Labels hint at the category of motivation (customer-request, incident-followup, compliance). Milestones tie work to deadlines, which often reveal motivation. | |
| 30 | 24 | |
| 31 | 25 | ## What good evidence looks like here |
| 32 | 26 | |
| 33 | −- An issue description that states the business problem: "Customer Acme needs X because of their SOC2 audit" | |
| 34 | −- A comment that records a decision: "We decided to go with approach B because approach A would require touching the billing service" | |
| 27 | +- An issue description stating the business problem: "Customer Acme needs X because of their SOC2 audit" | |
| 28 | +- A comment recording a decision: "We decided to go with approach B because approach A would require touching the billing service" | |
| 35 | 29 | - A parent issue titled like an initiative: "Q3 Enterprise Readiness" or "Reduce Payment Failures" |
| 36 | 30 | - An attached PRD or spec |
| 37 | 31 | - Labels like `customer:acme`, `incident-followup`, `compliance`, `perf-regression` |
| @@ -39,7 +33,7 @@ Good queries: · 1 unmodified line | ||
| 39 | 33 | ## Common pitfalls |
| 40 | 34 | |
| 41 | 35 | - **Scope drift.** The ticket the PR references may have been closed and reopened with a different scope. Read the whole history. |
| 42 | −- **Ticket templates filled in mechanically.** Some teams require tickets to have "Why" sections but fill them with boilerplate. If the text is generic ("improve user experience"), it's probably not a real answer. | |
| 36 | +- **Mechanical templates.** Some teams require "Why" sections but fill them with boilerplate. Generic text ("improve user experience") is probably not a real answer. | |
| 43 | 37 | - **Stale tickets.** Old tickets often reflect a version of the plan that changed. Check dates and cross-reference with the code's ship date. |
| 44 | 38 | - **Closed-as-duplicate chains.** Follow the duplicate-of relationships back to the canonical ticket. |
| 45 | 39 | - **Private workspace content.** If you can't access an issue, note that as a gap rather than guessing. |
| @@ -48,7 +42,7 @@ Good queries: · 2 unmodified lines | ||
| 48 | 42 | |
| 49 | 43 | For each relevant ticket: |
| 50 | 44 | - Ticket ID and title |
| 51 | −- The problem/motivation quoted from the description or comments (not paraphrased, the synthesizer needs the exact text to cite) | |
| 45 | +- The problem/motivation quoted from the description or comments (not paraphrased; the synthesizer needs the exact text to cite) | |
| 52 | 46 | - Labels, parent issue, project |
| 53 | 47 | - Author, created date, closed date |
| 54 | 48 | - Link to the ticket if available |
| @@ -11,11 +11,11 @@ · 10 unmodified lines | ||
| 11 | 11 | - Runbooks that may explain defensive code |
| 12 | 12 | - Strategy documents that set priorities |
| 13 | 13 | |
| 14 | −Notion is often where "why" lives in long-form before it becomes code. If a significant feature exists, there's usually a doc. | |
| 14 | +Notion is where "why" often lives in long-form before it becomes code. A significant feature usually has a doc. | |
| 15 | 15 | |
| 16 | 16 | ## How to search it |
| 17 | 17 | |
| 18 | −Use the Notion MCP available in your environment. | |
| 18 | +Use the Notion MCP. | |
| 19 | 19 | |
| 20 | 20 | 1. **Keyword searches with `notion-search`.** Try: |
| 21 | 21 | - The feature name |
| @@ -23,14 +23,10 @@ Use the Notion MCP available in your environment. · 1 unmodified line | ||
| 23 | 23 | - Author handles (design docs are often authored before the code lands) |
| 24 | 24 | - Error strings or user-visible terms |
| 25 | 25 | - Time-bounded queries if you know when the code shipped |
| 26 | − | |
| 27 | −2. **Fetch candidate pages with `notion-fetch`.** Read the full content, not just the preview. Rationale is often buried mid-document. | |
| 28 | − | |
| 26 | +2. **Fetch candidate pages with `notion-fetch`.** Read the full content, not the preview; rationale is often buried mid-document. | |
| 29 | 27 | 3. **Follow backlinks and child pages.** Design docs often have sub-pages for alternatives considered, appendices, or implementation notes. |
| 30 | − | |
| 31 | 28 | 4. **Check related databases.** `notion-query-data-sources` and `notion-query-meeting-notes` can surface meeting notes that discussed the decision. |
| 32 | − | |
| 33 | −5. **Search author-specific spaces.** If the PR author has a personal notebook (common at some companies), it may contain exploratory thinking that preceded the code. | |
| 29 | +5. **Search author-specific spaces.** If the PR author has a personal notebook (common at some companies), it may hold exploratory thinking that preceded the code. | |
| 34 | 30 | |
| 35 | 31 | ## What good evidence looks like here |
| 36 | 32 | |
| @@ -42,9 +38,9 @@ Use the Notion MCP available in your environment. · 5 unmodified lines | ||
| 42 | 38 | |
| 43 | 39 | ## Common pitfalls |
| 44 | 40 | |
| 45 | −- **Outdated docs.** Specs are often written before implementation and then not updated. The doc may describe a plan that was changed during implementation. Cross-check against the actual PR. | |
| 46 | −- **Doc vs. reality drift.** A spec may say "we'll do X" but the code actually does Y. Flag the divergence in findings; the synthesizer will surface the contradiction. | |
| 47 | −- **Boilerplate templates.** Some orgs require a "Why" section that gets filled in with fluff. Look for specificity. | |
| 41 | +- **Outdated docs.** Specs are often written before implementation and not updated; the doc may describe a plan that changed. Cross-check against the actual PR. | |
| 42 | +- **Doc vs. reality drift.** A spec may say "we'll do X" but the code actually does Y. Flag the divergence; the synthesizer will surface the contradiction. | |
| 43 | +- **Boilerplate templates.** Some orgs require a "Why" section that gets filled with fluff. Look for specificity. | |
| 48 | 44 | - **Unlinked docs.** The most relevant doc may not be linked from anywhere. Broad keyword searches help. |
| 49 | 45 | - **Multiple drafts.** If a topic has multiple docs, find the one that was finalized or most recently updated. Check dates. |
| 50 | 46 | - **Access-restricted pages.** If you can't access a page, note it as a gap. |
| @@ -2,24 +2,22 @@ · 1 unmodified line | ||
| 2 | 2 | |
| 3 | 3 | ## What this source contains |
| 4 | 4 | |
| 5 | −Sentry is the archive of things that actually went wrong. For defensive, corrective, or error-handling code, Sentry often holds the direct motivation: the specific exceptions, stack traces, and frequencies that pushed someone to add a check, catch, retry, or fallback. | |
| 6 | − | |
| 7 | −Relevant content: | |
| 5 | +Sentry is the archive of things that went wrong. For defensive, corrective, or error-handling code, it often holds the direct motivation: the specific exceptions, stack traces, and frequencies that pushed someone to add a check, catch, retry, or fallback. | |
| 8 | 6 | |
| 9 | 7 | - **Issues.** Grouped errors with counts, first/last seen timestamps, affected releases, and comments |
| 10 | 8 | - **Events.** Individual error instances within an issue (stack traces, tags, user context) |
| 11 | 9 | - **Releases.** Deployment records with associated issues (useful for "which version fixed this?") |
| 12 | 10 | - **Replays.** Session recordings of user-facing errors (if enabled) |
| 13 | −- **Profiles.** Performance profiling data (less useful for "why" questions; more for "how slow") | |
| 11 | +- **Profiles.** Performance profiling data (less useful for "why"; more for "how slow") | |
| 14 | 12 | - **Issue comments & assignments.** Sometimes contain engineer notes on root cause |
| 15 | 13 | |
| 16 | −The most valuable thing Sentry provides is **temporal correlation**: "issue X was created 2024-01-02, peaked at 500 events/day, stopped appearing after release v2.14.0 on 2024-01-15, which is the release that shipped the defensive check." | |
| 14 | +The most valuable thing Sentry provides is **temporal correlation**: "issue X was created 2024-01-02, peaked at 500 events/day, stopped appearing after release v2.14.0 on 2024-01-15, the release that shipped the defensive check." | |
| 17 | 15 | |
| 18 | 16 | ## How to search it |
| 19 | 17 | |
| 20 | −Use the Sentry MCP available in your environment. | |
| 18 | +Use the Sentry MCP. | |
| 21 | 19 | |
| 22 | −1. **Orient.** If you don't already know the project slug and organization, use: | |
| 20 | +1. **Orient.** If you don't know the project slug and organization: | |
| 23 | 21 | |
| 24 | 22 | ``` |
| 25 | 23 | find_organizations |
| @@ -32,23 +30,19 @@ Use the Sentry MCP available in your environment. · 6 unmodified lines | ||
| 32 | 30 | search_issues (natural language, e.g., "errors in PaymentService timeout", "unhandled exceptions in uploadFile") |
| 33 | 31 | ``` |
| 34 | 32 | |
| 35 | − Good query components: | |
| 36 | − - Exception class names the target handles | |
| 37 | − - Function or class name of the target | |
| 38 | − - Error message strings the target checks for | |
| 39 | − - File path of the target | |
| 33 | + Good query components: exception class names the target handles, the function or class name of the target, error message strings the target checks for, the file path of the target. | |
| 40 | 34 | |
| 41 | 35 | 3. **Narrow by release and time window.** |
| 42 | 36 | |
| 43 | 37 | ``` |
| 44 | 38 | search_issue_events (filter by release, time, environment, trace ID, tags) |
| 45 | − get_issue_tag_values (for a specific issue, see how it's distributed across versions, users, environments) | |
| 39 | + get_issue_tag_values (for an issue, see distribution across versions, users, environments) | |
| 46 | 40 | ``` |
| 47 | 41 | |
| 48 | − When you have a suspected issue, check: | |
| 49 | − - **First seen.** When did this error start appearing? | |
| 42 | + For a suspected issue, check: | |
| 43 | + - **First seen.** When did the error start appearing? | |
| 50 | 44 | - **Last seen.** When did it stop? Does it line up with the target's ship date? |
| 51 | − - **Affected releases.** Which versions saw the issue? Which was the fix? | |
| 45 | + - **Affected releases.** Which versions saw it? Which was the fix? | |
| 52 | 46 | - **Frequency trajectory.** Did it spike, then get resolved? |
| 53 | 47 | |
| 54 | 48 | 4. **Pull the full event for context.** |
| @@ -57,7 +51,7 @@ Use the Sentry MCP available in your environment. · 2 unmodified lines | ||
| 57 | 51 | get_sentry_resource (pass a Sentry URL or type+ID) |
| 58 | 52 | ``` |
| 59 | 53 | |
| 60 | − Look at the stack trace. Does it pass through the target code? Look at tags and breadcrumbs. Do they match the conditions the target defends against? | |
| 54 | + Does the stack trace pass through the target code? Do the tags and breadcrumbs match the conditions the target defends against? | |
| 61 | 55 | |
| 62 | 56 | 5. **Check releases that landed near the target.** |
| 63 | 57 | |
| @@ -73,11 +67,11 @@ Use the Sentry MCP available in your environment. · 9 unmodified lines | ||
| 73 | 67 | analyze_issue_with_seer |
| 74 | 68 | ``` |
| 75 | 69 | |
| 76 | − Seer produces AI root-cause analyses. They're useful as a hypothesis generator, but treat them as another source of inference, not as authoritative. The actual events and stack traces are the primary evidence; Seer's narrative is secondary. | |
| 70 | + Seer produces AI root-cause analyses. Useful as a hypothesis generator, but treat them as inference, not authoritative. The actual events and stack traces are the primary evidence; Seer's narrative is secondary. | |
| 77 | 71 | |
| 78 | 72 | ## What good evidence looks like here |
| 79 | 73 | |
| 80 | −- An issue whose **first seen** is shortly before the target's PR, and **last seen** shortly after, suggesting the target addressed this error | |
| 74 | +- An issue whose **first seen** is shortly before the target's PR and **last seen** shortly after, suggesting the target addressed this error | |
| 81 | 75 | - Stack traces that pass through or land on the target function, showing the exact failure mode being defended against |
| 82 | 76 | - A comment on the issue from the PR author describing the fix |
| 83 | 77 | - The target's PR description or commit message referencing a Sentry issue URL or ID |
| @@ -85,12 +79,12 @@ Use the Sentry MCP available in your environment. · 1 unmodified line | ||
| 85 | 79 | |
| 86 | 80 | ## Common pitfalls |
| 87 | 81 | |
| 88 | −- **Grouping drift.** Sentry groups errors by fingerprint. Changes to the code (e.g., refactors, renames) can cause the "same" error to be tracked under a new issue ID. If an issue ends abruptly, the error may have just been regrouped. Check for new issues immediately after. | |
| 89 | −- **Release correlation is noisy.** A release contains many commits. An issue stopping at v2.14.0 doesn't prove the target code fixed it. Another change in the same release might have. Cross-reference with the target's exact commit. | |
| 82 | +- **Grouping drift.** Sentry groups errors by fingerprint. Refactors or renames can track the "same" error under a new issue ID. If an issue ends abruptly, the error may have just been regrouped. Check for new issues immediately after. | |
| 83 | +- **Release correlation is noisy.** A release contains many commits. An issue stopping at v2.14.0 doesn't prove the target fixed it; another change in the same release might have. Cross-reference with the target's exact commit. | |
| 90 | 84 | - **Silent fixes.** Sometimes the error stops because upstream changed, not because of the defensive code. The correlation suggests the fix; it doesn't prove authorship. |
| 91 | −- **Resolved != fixed.** Issues in Sentry can be marked "resolved" manually without any code change. Treat `resolved` as a human marker, not as evidence that code fixed it. | |
| 92 | −- **Seer hallucinations.** Seer can generate confident-sounding explanations that aren't right. Always fall back to the actual events, stack traces, and timestamps when making claims. | |
| 93 | −- **Sampling.** Some projects sample events aggressively. A low event count doesn't mean the error was rare. It may just mean sampling was high. If in doubt, note the gap. | |
| 85 | +- **Resolved != fixed.** Issues can be marked "resolved" manually without any code change. Treat `resolved` as a human marker, not evidence that code fixed it. | |
| 86 | +- **Seer hallucinations.** Seer can generate confident-sounding explanations that aren't right. Fall back to the actual events, stack traces, and timestamps when making claims. | |
| 87 | +- **Sampling.** Some projects sample events aggressively. A low event count may just mean high sampling, not a rare error. If in doubt, note the gap. | |
| 94 | 88 | |
| 95 | 89 | ## What to return |
| 96 | 90 | |
| @@ -9,43 +9,36 @@ · 8 unmodified lines | ||
| 9 | 9 | - Post-merge discussions that explain why something was revisited |
| 10 | 10 | - DMs (usually not searchable, scope accordingly) |
| 11 | 11 | |
| 12 | −Slack is frequently where the *real* decisions got made, especially for smaller changes that didn't warrant a doc. It's also the most ephemeral source. Threads get deleted, channels get archived, and search quality degrades over time. | |
| 12 | +Slack is frequently where the *real* decisions got made, especially for smaller changes that didn't warrant a doc. It's also the most ephemeral source: threads get deleted, channels get archived, and search quality degrades over time. | |
| 13 | 13 | |
| 14 | 14 | ## How to search it |
| 15 | 15 | |
| 16 | −Slack MCP tools vary. Check which Slack MCP is available in your environment and inspect its tool schema first. It may require `mcp_auth`. If authentication fails, stop and report the gap. | |
| 17 | − | |
| 18 | −Search strategies: | |
| 19 | − | |
| 20 | −1. **Author-bounded search.** Search for messages from the PR author around the PR merge date. Limits search scope dramatically and often hits gold. | |
| 16 | +Slack MCP tools vary. Check which Slack MCP is available and inspect its tool schema first. It may require `mcp_auth`. If authentication fails, stop and report the gap. | |
| 21 | 17 | |
| 18 | +1. **Author-bounded search.** Messages from the PR author around the PR merge date. Limits scope dramatically and often hits gold. | |
| 22 | 19 | 2. **Keyword search for the feature name and key symbols.** Include misspellings and casual phrasings. |
| 23 | − | |
| 24 | −3. **PR URL search.** Slack often links PRs when they're being reviewed or discussed. Search for the PR URL (or just `/pull/<number>`). | |
| 25 | − | |
| 20 | +3. **PR URL search.** Slack often links PRs when they're reviewed or discussed. Search for the PR URL (or just `/pull/<number>`). | |
| 26 | 21 | 4. **Error string search.** If the code handles a specific error, search for the error string. Incident threads often surface. |
| 27 | − | |
| 28 | 22 | 5. **Channel-scoped search.** Narrow to likely channels: |
| 29 | 23 | - `#eng-*`. Engineering discussions |
| 30 | 24 | - `#proj-*`. Project channels |
| 31 | 25 | - `#incident-*` / `#sev-*`. Incident channels |
| 32 | 26 | - Team-specific channels for the owning team |
| 33 | 27 | - Design review channels |
| 34 | − | |
| 35 | 28 | 6. **Thread traversal.** When you find a relevant message, fetch the whole thread. The decision often lives in the replies. |
| 36 | 29 | |
| 37 | 30 | ## What good evidence looks like here |
| 38 | 31 | |
| 39 | 32 | - A thread where tradeoffs were explicitly debated ("I was going to use A but B is better because...") |
| 40 | −- An incident channel message that describes the bug the code prevents | |
| 33 | +- An incident channel message describing the bug the code prevents | |
| 41 | 34 | - A question from a reviewer and an authoritative answer from the author or lead |
| 42 | 35 | - A reference to a meeting where a decision was made |
| 43 | 36 | - A message from a product manager or customer-facing engineer explaining a customer ask |
| 44 | 37 | |
| 45 | 38 | ## Common pitfalls |
| 46 | 39 | |
| 47 | −- **Channel archaeology limits.** Very old Slack messages may be gone due to retention policies. If you can't find anything from before a certain date, note the retention cliff. | |
| 48 | −- **Unsearched DMs.** Many decisions happen in DMs that aren't searchable. You'll miss them; that's a known limitation of this source. | |
| 40 | +- **Channel archaeology limits.** Very old messages may be gone due to retention policies. If you can't find anything before a certain date, note the retention cliff. | |
| 41 | +- **Unsearched DMs.** Many decisions happen in DMs that aren't searchable. You'll miss them; that's a known limitation. | |
| 49 | 42 | - **Speculative jokes as "decisions."** Slack is casual. "Lol just do the thing" isn't a decision, even if it preceded the commit. Look for considered discussion. |
| 50 | 43 | - **Context collapse in single messages.** Without the thread, a single message often reads differently than in context. Always fetch threads. |
| 51 | 44 | - **Auth failures.** If the MCP isn't authenticated, stop. Don't make up findings. Report that Slack wasn't searchable. |
| @@ -1,10 +1,10 @@ | ||
| 1 | 1 | # Synthesizer Prompt Template |
| 2 | 2 | |
| 3 | −Use this template to build the prompt for the synthesizer subagent. Fill in the placeholders. | |
| 3 | +Build the synthesizer's prompt from this template; fill in the placeholders. | |
| 4 | 4 | |
| 5 | 5 | --- |
| 6 | 6 | |
| 7 | −You are answering a "why" question about a piece of code by synthesizing findings from multiple 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). Your job is to produce a confidence-weighted, evidence-cited narrative that honestly communicates what the evidence supports and just as honestly communicates what it doesn't. | |
| 7 | +You are answering a "why" question about a piece of code by synthesizing findings from multiple 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 honestly communicates what the evidence supports and what it doesn't. | |
| 8 | 8 | |
| 9 | 9 | ## The Question |
| 10 | 10 | |
| @@ -37,17 +37,12 @@ You MUST follow the framework in `references/epistemics.md`. Read it in full bef · 26 unmodified lines | ||
| 37 | 37 | |
| 38 | 38 | ## Instructions |
| 39 | 39 | |
| 40 | −1. **Read all investigator findings.** The investigators gathered raw evidence, not conclusions. You're the one who weighs it. | |
| 41 | − | |
| 42 | −2. **Reconcile overlapping findings.** Multiple investigators may have cited the same PR, ticket, or doc. Merge into a single, authoritative reference for that item. | |
| 43 | − | |
| 44 | −3. **Identify contradictions.** If two items of evidence disagree, don't pick one. Surface both in the output. | |
| 45 | − | |
| 46 | −4. **Calibrate confidence.** For each claim you want to make, ask: what's the evidence, and what tier does it belong in? If it's Direct, cite it and state it plainly. If it's Inferred, hedge it and explain the inference. If it's Speculative, mark it explicitly. If you have no evidence, put it in the gaps section. | |
| 47 | − | |
| 48 | −5. **Verify citations by spot-checking.** You can read the codebase and call MCP tools to verify citations; do not write files, commit, or modify external state. If an investigator cited something and you're uncertain it exists or says what they claim, check it. Don't propagate errors. | |
| 49 | − | |
| 50 | −6. **Don't overreach.** The user will act on your output. It's better to leave an open question open than to fill it with a confident-sounding guess. | |
| 40 | +1. **Read all investigator findings.** They gathered raw evidence, not conclusions. You weigh it. | |
| 41 | +2. **Reconcile overlapping findings.** Multiple investigators may have cited the same PR, ticket, or doc. Merge into a single, authoritative reference. | |
| 42 | +3. **Identify contradictions.** If two items of evidence disagree, don't pick one. Surface both. | |
| 43 | +4. **Calibrate confidence.** For each claim, identify the evidence and the tier. State Direct claims plainly with a citation. Hedge Inferred claims and explain the inference. Mark Speculative claims explicitly. Put claims with no evidence in the gaps section. | |
| 44 | +5. **Verify citations by spot-checking.** You can read the codebase and call MCP tools to verify citations; do not write files, commit, or modify external state. If you're uncertain a cited item exists or says what's claimed, check it. Don't propagate errors. | |
| 45 | +6. **Don't overreach.** The user will act on your output. Better to leave an open question open than to fill it with a confident-sounding guess. | |
| 51 | 46 | |
| 52 | 47 | ## Output Format |
| 53 | 48 | |
| @@ -61,13 +56,11 @@ Restate the user's question in one or two sentences so the answer is anchored. · 7 unmodified lines | ||
| 61 | 56 | |
| 62 | 57 | ### The Code in Question |
| 63 | 58 | |
| 64 | −File paths, line ranges, key symbols. Two or three lines. Enough to orient a reader who lands here cold. | |
| 59 | +File paths, line ranges, key symbols. Two or three lines to orient a reader who lands here cold. | |
| 65 | 60 | |
| 66 | 61 | ### What We Found |
| 67 | 62 | |
| 68 | −**Claims with direct evidence.** Each bullet is a thing we have textual evidence for. Quote or paraphrase the source and cite precisely. | |
| 69 | − | |
| 70 | −Format each finding like: | |
| 63 | +**Claims with direct evidence**, one per bullet. Quote or paraphrase the source and cite precisely. Format each finding like: | |
| 71 | 64 | |
| 72 | 65 | - **[Direct]** {Claim}. Source: [PR #123](url) / ticket ID / file:line. {Brief quote or paraphrase.} |
| 73 | 66 | - **[Supported]** {Claim}. Evidence: {list of items and what each contributes}. |
| @@ -76,11 +69,7 @@ Use `[Direct]` for single-source, explicit evidence. Use `[Supported]` when mult · 2 unmodified lines | ||
| 76 | 69 | |
| 77 | 70 | ### What We Can Reasonably Infer |
| 78 | 71 | |
| 79 | −**Claims that aren't explicitly stated anywhere but are well-supported by indirect evidence.** Each bullet must make the inference chain visible: "Given A and B, it's likely that C." | |
| 80 | − | |
| 81 | −Use hedged language: "appears to", "likely", "suggests", "is consistent with". | |
| 82 | − | |
| 83 | −Format: | |
| 72 | +**Claims that aren't explicitly stated anywhere but are well-supported by indirect evidence.** Make the inference chain visible: "Given A and B, it's likely that C." Use hedged language ("appears to", "likely", "suggests", "is consistent with"). Format: | |
| 84 | 73 | |
| 85 | 74 | - **[Inferred]** {Hedged claim}. Reasoning: {the specific evidence and the inference step}. |
| 86 | 75 | |
| @@ -88,9 +77,8 @@ If there's nothing to infer, skip this section. · 1 unmodified line | ||
| 88 | 77 | |
| 89 | 78 | ### Competing Hypotheses |
| 90 | 79 | |
| 91 | −**If the evidence fits multiple stories, present them.** Don't force a winner when the record doesn't support one. | |
| 80 | +**If the evidence fits multiple stories, present them.** Don't force a winner when the record doesn't support one. For each hypothesis: | |
| 92 | 81 | |
| 93 | −For each hypothesis: | |
| 94 | 82 | - **Hypothesis:** {one-sentence statement} |
| 95 | 83 | - **Evidence for:** {specific items} |
| 96 | 84 | - **Evidence against or missing:** {what would need to be true but isn't, or what counter-signals exist} |
| @@ -99,11 +87,10 @@ Skip this section if there's a single clear answer. · 2 unmodified lines | ||
| 99 | 87 | |
| 100 | 88 | ### What We Don't Know |
| 101 | 89 | |
| 102 | −**Explicit gaps.** Things the user asked that the evidence didn't answer. Sources that were searched and came up empty. Sources that weren't searchable at all, such as a missing real-time team chat MCP. | |
| 90 | +**Explicit gaps.** Things the user asked that the evidence didn't answer. Sources searched that came up empty. Sources that weren't searchable at all, such as a missing real-time team chat MCP. | |
| 103 | 91 | |
| 104 | −Be specific. "We searched the issue tracker for [query1], [query2], [query3] and found no issue discussing the rate-limit threshold" is useful. "We don't know why" is not. | |
| 92 | +Be specific. "We searched the issue tracker for [query1], [query2], [query3] and found no issue discussing the rate-limit threshold" is useful. "We don't know why" is not. Include: | |
| 105 | 93 | |
| 106 | −Include: | |
| 107 | 94 | - Specific questions that went unanswered |
| 108 | 95 | - Searches that returned nothing |
| 109 | 96 | - Sources that were unavailable (and why) |
| @@ -111,9 +98,7 @@ Include: · 1 unmodified line | ||
| 111 | 98 | |
| 112 | 99 | ### Sources Consulted |
| 113 | 100 | |
| 114 | −Bulleted list of what was actually searched. This lets the user judge coverage and redirect the investigation. | |
| 115 | − | |
| 116 | −Format: | |
| 101 | +Bulleted list of what was actually searched, so the user can judge coverage and redirect. Format: | |
| 117 | 102 | |
| 118 | 103 | - **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." |
| 119 | 104 | - **Issue / ticket tracker**: {ticket IDs and keyword searches}. Or "Not searched. No matching MCP available in this environment." |
| @@ -125,7 +110,7 @@ Format: · 5 unmodified lines | ||
| 125 | 110 | |
| 126 | 111 | ### Confidence Summary |
| 127 | 112 | |
| 128 | −One or two sentences summarizing your overall confidence in the answer. E.g.: | |
| 113 | +One or two sentences summarizing your overall confidence. E.g.: | |
| 129 | 114 | |
| 130 | 115 | > "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." |
| 131 | 116 | |
| @@ -135,7 +120,7 @@ One or two sentences summarizing your overall confidence in the answer. E.g.: · 3 unmodified lines | ||
| 135 | 120 | |
| 136 | 121 | Before finalizing, review your output against this checklist: |
| 137 | 122 | |
| 138 | −1. Does every claim in "What We Found" have a citation? If not, either add one or move the claim to "Inferred" or "Hypotheses." | |
| 123 | +1. Does every claim in "What We Found" have a citation? If not, add one or move the claim to "Inferred" or "Hypotheses." | |
| 139 | 124 | 2. Is the phrasing tier-appropriate? (Direct claims can use "because"; Inferred claims cannot.) |
| 140 | 125 | 3. Did you surface any contradictions you noticed, or did you quietly pick one? |
| 141 | 126 | 4. Does the "What We Don't Know" section exist and name specific gaps? If it's empty or missing, be suspicious. Historical investigations almost always have gaps. |
| @@ -147,4 +132,4 @@ If any item fails, revise before returning. · 5 unmodified lines | ||
| 147 | 132 | |
| 148 | 133 | ## A Final Note |
| 149 | 134 | |
| 150 | −The value of this output comes from its honesty, not its authority. A reader who takes your answer to a conversation with the original author, an engineering lead, or a product manager should be well-positioned to ask the right follow-up questions. The answer needs to be clear about what's known, what's inferred, and what's missing. Don't optimize for looking decisive. Optimize for being useful. | |
| 135 | +The value of this output comes from its honesty, not its authority. A reader who takes your answer to the original author, an engineering lead, or a product manager should be well-positioned to ask the right follow-up questions. Be clear about what's known, what's inferred, and what's missing. Don't optimize for looking decisive. Optimize for being useful. | |