Skip to content
Back to search

rewin0087-investigate

MarketplaceWorks with Claude CodeGitHub

Claude Code plugins by rewin0087

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rewin0087--claude-code-investigate/badge.svg)](/listings/rewin0087--claude-code-investigate)

HTML

<a href="/listings/rewin0087--claude-code-investigate"><img src="/api/listings/rewin0087--claude-code-investigate/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

As a Claude Code plugin (recommended)

In Claude Code (2.1.275 or later):

/plugin install investigate --marketplace rewin0087/claude-code-investigate

Or in two steps, which works on any version with plugins:

/plugin marketplace add rewin0087/claude-code-investigate
/plugin install investigate@rewin0087-investigate

From a shell: `claude plugin marketplace add rewin0087/claude-code-investigate && claude plugin install investigate@rewin0087-investigate`.

Claude Code namespaces plugin commands, so you run the plugin as **`/investigate:investigate`**. Update it with `claude plugin update investigate@rewin0087-investigate`.

As a standalone skill (plain `/investigate`)

If you'd rather type `/investigate`, clone it as a skill. For every project:

git clone https://github.com/rewin0087/claude-code-investigate.git ~/.claude/skills/investigate

Or for one project only, clone it into `<repo>/.claude/skills/investigate`. Update with `git -C ~/.claude/skills/investigate pull`.

**Requirements:** Python 3.8+ (standard library only) and git. The Ruby tracer needs Ruby 2.6+.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 24 lines
  1. {
  2. "name": "rewin0087-investigate",
  3. "owner": {
  4. "name": "rewin0087",
  5. "url": "https://github.com/rewin0087"
  6. },
  7. "description": "Claude Code plugins by rewin0087",
  8. "plugins": [
  9. {
  10. "name": "investigate",
  11. "source": "./",
  12. "description": "Trace and simulate data flow through your app; reproduce bugs and stack traces with an interactive report.",
  13. "version": "1.1.0",
  14. "category": "development",
  15. "keywords": [
  16. "debugging",
  17. "data-flow",
  18. "simulation",
  19. "tracing",
  20. "stack-trace"
  21. ]
  22. }
  23. ]
  24. }
README.md · README · 432 lines
  1. # claude-code-investigate: trace, simulate and debug data flow with Claude Code
  2. [![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-7c5cff)](https://github.com/rewin0087/claude-code-investigate#install)
  3. [![Version](https://img.shields.io/github/v/release/rewin0087/claude-code-investigate?sort=semver)](https://github.com/rewin0087/claude-code-investigate/releases)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  5. [![Website](https://img.shields.io/badge/docs-website-blue)](https://rewin0087.github.io/claude-code-investigate/)
  6. **`/investigate` is a debugging and data-flow simulation skill and plugin for [Claude Code](https://claude.com/claude-code).** Point it at an **endpoint**, a **method or class**, the **code you've highlighted**, a **bug report** or a **stack trace**, in **any tech stack**. It maps the flow from the raw input (an API or form request, or a method call) through **validation, branches, business logic, database CRUD, external API calls and state changes** to the **outcome**, and records the **file, line and method where each value changes**. It builds **realistic inputs** from your DB schema, factories and fixtures (or masked samples from your local DB), replays bugs on the **existing records they affected** (`Order#4512`), simulates **every path and edge case**, and can **run** them with a line-by-line runtime tracer. Runs go in your test environment, or in your **local development environment inside a rolled-back sandbox** that follows every DB read and write. It **reproduces errors** and **pin-points bugs** with fixes. It opens an **interactive HTML report**.
  7. It runs on your existing Claude Code session, in the terminal, VS Code or JetBrains. You don't need an API key, a server or extra packages.
  8. ![A scenario in the investigation report: the input, outcome and path decisions, then a step-by-step data timeline with every value before and after](docs/images/report-scenario.png)
  9. ## Features
  10. - **Input to outcome**: request parsing, strong params / DTOs, validations, callbacks, policies, services, ORM queries, transactions, external API clients, jobs, events and the response. Every step has a file, line and method.
  11. - **Every path as a named scenario**, such as "Sign in with valid credentials", "…with an invalid password", "…when the account is locked" or "…with malformed JSON". Each has its input, the branch it takes at every condition, and the outcome. Its status is pass, expected error, bug, risk or reproduced.
  12. - **Edge cases**: missing or wrong-typed fields, blank vs nil, boundaries, unicode and whitespace, duplicates, other tenants' records, permissions, concurrency, retries, and failing or timing-out external APIs.
  13. - **Data timeline**: each value **before → after** at every step, with the SQL issued and the HTTP calls made. A state panel shows all the data at any step as you scrub through the scenario.
  14. - **Realistic inputs**: built from the DB schema (types, NOT NULL, unique, foreign keys, enums), factories (FactoryBot, factory_boy, Fishery…), fixtures, seeds and API contracts (OpenAPI, GraphQL, DTOs, validators). With `--db`, it also uses masked read-only samples from your local DB.
  15. - **Runtime tracers** for Python and Ruby/Rails, standard library only. They record calls with their arguments, every executed line and the locals, attributes or ActiveRecord fields it changed, SQL with bind values, outgoing HTTP, exceptions and return values. For other stacks, Claude writes a throwaway test that logs data snapshots.
  16. - **Stack trace reproduction**: parses Python, Ruby/Rails, JS/TS, Java/Kotlin, Go, PHP and .NET traces, maps the frames to your files, and starts at the deepest app frame. It builds a scenario that reproduces the error and points at the step where the bad value is **created**, not just where it blows up.
  17. - **Pin-pointed bugs**: the exact line, the value that makes it wrong, the scenarios that show it, a concrete fix with code, and references (framework docs, OWASP, CWE).
  18. - **Run on your development data, safely**: with `--env dev`, scenarios run against your local
  19. development database inside a **rolled-back sandbox** (an ActiveRecord / Django / SQLAlchemy
  20. transaction). Every read and write is recorded, the watched records are shown before → after,
  21. emails and jobs are captured instead of sent, outbound network is blocked, and any COMMIT that
  22. escapes the rollback is reported.
  23. - **Replay the records a bug affected**: name them (`--record Order#4512`, `"users where email = '…'"`,
  24. or just "order 4512" in your message). `records.py` fetches them read-only and masked, with
  25. their parents and children (via foreign keys or `*_id` columns), and the scenarios replay
  26. exactly that data.
  27. - **Database activity per scenario**: the tables read, and every INSERT / UPDATE / DELETE with
  28. its line and values.
  29. - **Your instructions**: bug reports, repro steps, expected behaviour, screenshots, ticket links, or free text after ` -- `.
  30. - **Highlight and go**: select a method or class in VS Code or JetBrains and run `/investigate`.
  31. - **Interactive report**: scenario list, data timeline with a state scrubber, flow and condition matrices, a code view that highlights the lines that actually ran, bugs, a reproduction view, keyboard navigation, dark mode, and Copy as Markdown.
  32. - **Results in the chat**: the verdict, a table of every scenario, the bugs, the reproduction, and a link to the report.
  33. - **Safe by default**: it never modifies your repo, executes only in the test environment, makes no real outbound calls, reads the DB read-only on localhost only, and masks secrets and personal data.
  34. ## Install
  35. ### As a Claude Code plugin (recommended)
  36. In Claude Code (2.1.275 or later):
  37. ```text
  38. /plugin install investigate --marketplace rewin0087/claude-code-investigate
  39. ```
  40. Or in two steps, which works on any version with plugins:
  41. ```text
  42. /plugin marketplace add rewin0087/claude-code-investigate
  43. /plugin install investigate@rewin0087-investigate
  44. ```
  45. From a shell: `claude plugin marketplace add rewin0087/claude-code-investigate && claude plugin install investigate@rewin0087-investigate`.
  46. Claude Code namespaces plugin commands, so you run the plugin as **`/investigate:investigate`**. Update it with `claude plugin update investigate@rewin0087-investigate`.
  47. ### As a standalone skill (plain `/investigate`)
  48. If you'd rather type `/investigate`, clone it as a skill. For every project:
  49. ```bash
  50. git clone https://github.com/rewin0087/claude-code-investigate.git ~/.claude/skills/investigate
  51. ```
  52. Or for one project only, clone it into `<repo>/.claude/skills/investigate`. Update with `git -C ~/.claude/skills/investigate pull`.
  53. **Requirements:** Python 3.8+ (standard library only) and git. The Ruby tracer needs Ruby 2.6+.
  54. ## Usage
  55. ```text
  56. /investigate "POST /users/sign_in" # an endpoint
  57. /investigate AuthService#sign_in # a method or class
  58. /investigate app/services/checkout.rb:40-90 # a line range
  59. /investigate # the code highlighted in your editor
  60. /investigate --trace crash.log # reproduce a stack trace
  61. /investigate --bug JIRA-123.md -- locked users can still log in
  62. /investigate Orders::Checkout.call --run # run the scenarios with the tracer (test env)
  63. /investigate "POST /api/orders" --db --scenarios 12 # realistic inputs from masked local-DB rows
  64. /investigate RefundService#call --env dev --record Order#4512 -- refunds on this order exceed the total
  65. /investigate refund flow --focus concurrency -- two refunds for the same order at once
  66. ```
  67. | Option | Meaning |
  68. |---|---|
  69. | target | `file`, `file:a-b`, `file#La-Lb`, `@file`, `Class#method`, `Mod::Class.method`, `"VERB /path"`, a job / event / mutation name, or plain words |
  70. | `--selection` / `--file` | the editor selection / the open file. A selection is used automatically when there's no other target |
  71. | `--trace <file\|text>` | a stack trace or error log to reproduce. A trace pasted in the chat works too |
  72. | `--bug`, `--context` `<file\|url\|text>` | a bug report, repro steps, spec, screenshots or ticket links (repeatable) |
  73. | `-- text` | free-text instructions: how to reproduce, what to simulate, which inputs to use, what "correct" means |
  74. | `--run` / `--static` | always execute / never execute. By default it simulates, and asks before running a reproduction |
  75. | `--env test\|dev` | where executed scenarios run: the test environment (default), or your local development DB inside a rolled-back sandbox (it always asks first) |
  76. | `--record <ref>` | existing records to inspect and replay: `Model#id`, `table:id`, `"table where <condition>"` (repeatable) |
  77. | `--db [url]` | allow read-only, masked sample queries against a local dev/test database |
  78. | `--scenarios N` | aim for about N scenarios |
  79. | `--focus <area>` | put more weight on an area (security, validation, payments, concurrency…) |
  80. | `--no-open` | don't open the browser |
  81. ### Reproduce a bug or a stack trace
  82. Give it the trace (`--trace`, or paste it), the bug report (`--bug`, a file, URL or text) and any instructions after ` -- `. It:
  83. 1. maps the trace frames to your files, innermost first, and starts at the deepest frame in your code
  84. 2. walks outward to find which input and which existing records reach the failing line
  85. 3. builds a `reproduction` scenario, and runs it in the test environment when you allow it (`--run`)
  86. 4. reports the root cause: the step where the bad value is **created**, not only where it raises
  87. ### Replay a bug on your development data
  88. Name the records the bug hit, and let it run on the development environment:
  89. ```text
  90. /investigate RefundService#call --env dev --record Order#4512 -- customer was refunded more than they paid
  91. ```
  92. 1. `records.py` reads `Order#4512` from your local dev DB, together with its parents and children
  93. (via foreign keys or `*_id` columns). It is read-only and masked.
  94. 2. Claude spots the values that drive the bug (here: `refunded_cents` 1500 of `total_cents` 2000).
  95. 3. After you approve, a harness runs the real code on that record inside a sandbox:
  96. ```ruby
  97. InvestigateTrace.sandbox("SC3", watch: { order: -> { Order.find(4512) } }) do
  98. RefundService.new(4512, 1000).call
  99. end
  100. ```
  101. ```text
  102. Database activity:
  103. reads: orders ×1
  104. INSERT refunds at app/services/refund.rb:10 params=[4512, 1000]
  105. UPDATE orders at app/services/refund.rb:13 params=["refunded", 2500, 4512]
  106. Sandbox SC3: rollback=active_record, rolled back=True, commits=0
  107. watch order.status: pending → refunded
  108. watch order.refunded_cents: 1500 → 2500
  109. email captured (not sent): Refund issued
  110. job captured (not enqueued): SyncLedgerJob
  111. ```
  112. Your dev database is unchanged afterwards. If the code commits on its own (a separate connection,
  113. or an explicit commit), the sandbox reports it, and the summary tells you which rows persisted.
  114. In Python it's `with investigate_trace.sandbox("SC3", rollback="django", watch={...}):` (or pass a
  115. SQLAlchemy session / DB-API connection).
  116. ### Investigate the code you've highlighted
  117. The VS Code and JetBrains extensions share your selection with Claude Code. Highlight a method or class and run `/investigate`; a selection becomes the target automatically. `/investigate --file` targets the whole open file.
  118. ### Report keyboard shortcuts
  119. | Key | Action |
  120. |---|---|
  121. | `j` / `k` | next / previous step in the data timeline |
  122. | `]` / `[` | next / previous scenario |
  123. | `c` | open the code of the current step |
  124. | `o` / `f` / `b` / `r` | overview, flow map, bugs, reproduction |
  125. | `/` | filter scenarios |
  126. | `t` | toggle dark mode |
  127. | `Esc` | close the code view |
  128. ## How it works
  129. ### Workflow: from input to outcome
  130. ```mermaid
  131. flowchart TD
  132. subgraph IN["1 - Input"]
  133. A1["Target<br/>endpoint, Class#method,<br/>file:lines, editor selection"]
  134. A2["Stack trace<br/>--trace or pasted"]
  135. A3["Bug report and instructions<br/>--bug, screenshots, links, -- text"]
  136. A4["Flags<br/>--run, --env dev, --db, --focus"]
  137. A5["Reference records<br/>--record Order#4512"]
  138. end
  139. subgraph PREP["2 - Prepare: deterministic scripts"]
  140. B1["prepare.py<br/>resolve the target,<br/>create .investigate/slug/"]
  141. B2["stacktrace.py<br/>frames to repo lines,<br/>deepest app frame"]
  142. B3["discover.py<br/>stack, schema, factories,<br/>contracts, routes, tests, DB config"]
  143. B5["records.py<br/>the records the bug hit,<br/>parents and children"]
  144. B4[("meta.json, context.json,<br/>stacktrace.json, discovery.json")]
  145. end
  146. subgraph AI["3 - Simulate: Claude Code"]
  147. C1["Map the flow<br/>nodes and conditions,<br/>callbacks, jobs, error handlers"]
  148. C2["Build inputs<br/>schema, factories, fixtures,<br/>contracts, masked DB rows"]
  149. C3["Enumerate scenarios<br/>every branch outcome<br/>plus edge cases"]
  150. C4["Walk each scenario<br/>value before and after,<br/>SQL, HTTP, state"]
  151. C5["Reproduce<br/>the input that reaches<br/>the failing line"]
  152. C6["Findings<br/>bugs, fixes, insights,<br/>web references"]
  153. C7[("investigation.json")]
  154. end
  155. subgraph RUN["4 - Execute: optional"]
  156. D1["Harness in .investigate/<br/>test env, or dev env in a<br/>rolled-back sandbox"]
  157. D2["trace_py.py / trace_rb.rb<br/>per-line changes, DB reads<br/>and writes, HTTP, watches"]
  158. D3["trace_digest.py<br/>readable timeline,<br/>lines that ran"]
  159. end
  160. subgraph RENDER["5 - Validate and render"]
  161. E1{"Anchors, ids,<br/>edge cases, fixes,<br/>references OK?"}
  162. E2["report.html<br/>interactive data timeline"]
  163. E3["summary.md<br/>posted in the chat"]
  164. end
  165. A1 & A3 & A4 --> B1
  166. A2 --> B2
  167. B1 --> B3 --> B4
  168. B2 --> B4
  169. A5 --> B5 --> B4
  170. B4 --> C1 --> C2 --> C3 --> C4
  171. C3 -. --run or approved .-> D1 --> D2 --> D3 --> C4
  172. C4 --> C5 --> C6 --> C7
  173. C7 --> E1
  174. E1 -- "no: ACTION REQUIRED" --> C3
  175. E1 -- yes --> E2 & E3
  176. ```
  177. | Stage | Who does it | Output |
  178. |---|---|---|
  179. | **1. Input** | You: a target, a trace, a bug report, instructions, flags | what to investigate |
  180. | **2. Prepare** | `prepare.py`, `stacktrace.py`, `discover.py`: deterministic, no AI | `meta.json`, `context.json`, `stacktrace.json`, `discovery.json` |
  181. | **3. Simulate** | Claude Code, guided by `SKILL.md` | `investigation.json` |
  182. | **4. Execute** (optional) | your test runner + `trace_py.py` / `trace_rb.rb` | `trace/<scenario>.json` |
  183. | **5. Validate and render** | `render.py`: checks every file:line, id and reference | `report.html`, `summary.md` |
  184. The scripts handle the exact parts: which definition a symbol refers to, which repo line a stack frame is, what the schema and factories say, what the code actually did at runtime, and whether every file:line in the report exists. Claude does the reasoning: the flow, the scenarios, the root cause and the fix. `render.py` rejects any step that points at a line that doesn't exist. It warns when edge cases, fixes, references or the reproduction mapping are missing, and Claude fixes them before replying.
  185. ### Step by step
  186. ```mermaid
  187. sequenceDiagram
  188. actor You
  189. participant CC as Claude Code
  190. participant S as Scripts
  191. participant T as Test env + tracer
  192. participant W as Web
  193. participant R as HTML report
  194. You->>CC: /investigate target [--trace] [--bug] [-- instructions]
  195. CC->>S: prepare.py
  196. S-->>CC: entry point candidates, context digest
  197. opt stack trace given
  198. CC->>S: stacktrace.py
  199. S-->>CC: frames mapped to repo lines, START_AT
  200. end
  201. CC->>S: discover.py
  202. S-->>CC: schema, factories, contracts, routes, tests, DB config
  203. CC->>CC: map nodes and conditions, build inputs, enumerate scenarios
  204. opt --db
  205. CC->>S: dbquery.py (read-only, masked)
  206. S-->>CC: sample rows
  207. end
  208. opt reference records named (--record)
  209. CC->>S: records.py (read-only, masked)
  210. S-->>CC: the records + parents and children
  211. end
  212. opt --run, or approved (test env, or dev env in a rolled-back sandbox)
  213. CC->>T: harness under trace_py.py / trace_rb.rb
  214. T-->>CC: trace/SC1.json
  215. CC->>S: trace_digest.py
  216. S-->>CC: per-line changes, DB activity, sandbox watches
  217. end
  218. CC->>W: framework docs, OWASP / CWE, library issues
  219. W-->>CC: references
  220. CC->>CC: steps, outcomes, bugs, reproduction → investigation.json
  221. CC->>S: render.py
  222. S-->>R: report.html
  223. S-->>CC: summary.md
  224. CC-->>You: verdict, scenario table, bugs, link to the report
  225. You->>R: scrub the timeline, open the code, copy as Markdown
  226. ```
  227. ### The result
  228. You get two outputs: a summary in the chat (below), and the interactive report in your browser.
  229. ```text
  230. ## Investigation: Sign-in: POST /sessions
  231. **🐞 Bug found** — Locked accounts can still sign in, and a non-string email crashes the endpoint with a 500
  232. Target: `POST /sessions → handle_sign_in → AuthService#sign_in` · Scenarios: 9 (2 executed with the tracer, 7 simulated)
  233. | # | Scenario | Outcome | Status |
  234. | SC1 | Sign in with valid credentials | 200 {user_id, token} | ✅ pass |
  235. | SC3 | Third wrong password locks the account | 401, account locked in the DB | 🛑 expected_error |
  236. | SC4 | Locked user signs in with the correct password | 200 — signed in although locked | 🐞 bug |
  237. | SC6 | Email sent as a number | 500 AttributeError | 🎯 reproduced |
  238. ### Bugs
  239. 1. **[major] Locked accounts can sign in** `app/auth.py:25`
  240. Root cause: `locked_at` is written at app/auth.py:29 but never read.
  241. Fix: Reject locked users before checking the password, and reset `failed_attempts` on success.
  242. ### Reproduction
  243. Error: `AttributeError: 'int' object has no attribute 'strip'` · Confirmed by running it. Fails at SC6 step 2.
  244. Full report (data timeline per scenario, flow map, code): report.html
  245. ```
  246. **Report layout**
  247. ```text
  248. +--------------------------------------------------------------------------------+
  249. | Sign-in: POST /sessions [POST /sessions -> AuthService#sign_in] [BUG FOUND] |
  250. +-----------------------+--------------------------------------------------------+
  251. | Overview | SC4 Locked user signs in with the correct password |
  252. | Flow map 9 nodes | +- Input ----------------+ +- Outcome --------------+ |
  253. | Bugs 2 | | POST /sessions {...} | | 200, but 403 expected | |
  254. | Reproduction | +------------------------+ +------------------------+ |
  255. | [Filter scenarios...] | Path decisions: C3 user is None -> F C5 pw ok -> F |
  256. | (Pass) (Bug) (Repro) | Data timeline [<] ======o======== [>] step 6 of 7 |
  257. | | (1) PARSE body.email | Data after step 6 |
  258. | * SC1 Valid sign in | (2) TRANSFORM email | email ana@ex.com |
  259. | * SC2 Unknown email | " Ana@Ex.com " -> "ana" | user.locked_at ... |
  260. | * SC4 Locked user < | (4) AUTH locked_at ignored | user.sign_in_count 1 |
  261. | * SC6 Email number | BUG B1 | db.users UPDATE |
  262. +-----------------------+--------------------------------------------------------+
  263. ```
  264. | Overview | Flow map |
  265. |---|---|
  266. | ![Overview: headline, scenario counts, how the flow works and the scenario table](docs/images/report-overview.png) | ![Flow map: which scenario passes through which node, and which way each condition went](docs/images/report-flow.png) |
  267. ![Code view: the lines that ran in the trace are green, with step and bug markers](docs/images/report-code.png)
  268. ### Runtime tracers
  269. ```bash
  270. # Python: use the project's interpreter so its packages import
  271. .venv/bin/python scripts/trace_py.py --root . --out .investigate/x/trace/SC1.json --entry sign_in \
  272. -- -m pytest .investigate/x/harness/sim_sc1.py -q
  273. # Ruby / Rails: wrap exactly the scenario in a harness...
  274. require "/path/to/scripts/trace_rb.rb"
  275. InvestigateTrace.record("SC1") { post "/users/sign_in", params: { user: { email:, password: } } }
  276. # ...or trace an existing spec as it is
  277. TRACE_AUTOSTART=1 TRACE_OUT=$PWD/.investigate/x/trace/SC1.json TRACE_ROOT=$PWD \
  278. RUBYOPT="-r/path/to/scripts/trace_rb.rb" RAILS_ENV=test bundle exec rspec spec/requests/sessions_spec.rb:12
  279. python3 scripts/trace_digest.py .investigate/x/trace/SC1.json
  280. ```
  281. ```text
  282. #15 → AuthService.sign_in(email=' Ana@Example.com ', password='[redacted]') [app/auth.py:18]
  283. #16 app/auth.py:19 email: ' Ana@Example.com ' → 'ana@example.com'
  284. #20 app/models.py:25 SQL SELECT … FROM users WHERE email = 'ana@example.com'
  285. #33 app/auth.py:20 user.failed_attempts: ∅ → 3; user.locked_at: ∅ → '2026-11-19T09:00:00'
  286. #40 app/auth.py:33 user.sign_in_count: 0 → 1
  287. #44 app/models.py:30 SQL UPDATE users SET failed_attempts = 3, … sign_in_count = 1 WHERE id = 1
  288. #58 ← handle_sign_in returned (200, {'user_id': 1, 'token': '[redacted]'}) [app/api.py:24]
  289. Executed lines: app/auth.py: 18-21,23,25,33-36 ← 26-31 (the wrong-password branch) did not run
  290. ```
  291. ### Safety
  292. - It writes only to `<repo>/.investigate/`, which is added to `.git/info/exclude`. Your files are never changed.
  293. - It executes only through your test runner in the test environment, where tests run in rolled-back transactions. It asks first unless you passed `--run`.
  294. - On the development environment (`--env dev`), it always asks first. It runs only against a local
  295. database (localhost, a socket or a sqlite file), and only inside a sandbox transaction that is
  296. rolled back. Emails and jobs are captured, and COMMITs that escape the rollback are reported.
  297. - Outbound network connections are blocked while tracing, except loopback (`--allow-host` /
  298. `TRACE_ALLOW_HOSTS` to allow one).
  299. - External APIs are stubbed with your tools (WebMock/VCR, responses, nock/MSW…). If they can't be stubbed, that part is simulated.
  300. - `dbquery.py` and `records.py` run one read statement at a time, against localhost or a sqlite file, in a read-only session, with a LIMIT. Secret columns are redacted and personal data is masked.
  301. - The tracers redact password, secret, token and key-like values. The report uses synthetic identities.
  302. ### Files
  303. ```
  304. SKILL.md instructions Claude follows (targets, safety, scenarios, reproduction, output)
  305. references/investigation-schema.md the investigation.json format Claude writes
  306. templates/report.html the self-contained interactive report
  307. scripts/ thin command-line entry points
  308. prepare.py target + context -> .investigate/<slug>/ (meta.json, context.json)
  309. stacktrace.py stack trace -> frames mapped to repo lines (stacktrace.json)
  310. discover.py schema, factories, contracts, routes, tests, DB config (discovery.json)
  311. dbquery.py read-only, masked sample rows from a local DB
  312. records.py the records a bug affected + their parents/children (read-only, masked)
  313. trace_py.py Python runtime tracer (standalone: run with the project's interpreter)
  314. trace_rb.rb Ruby / Rails runtime tracer (standalone: require it in a harness)
  315. trace_digest.py trace log -> readable per-line timeline
  316. render.py investigation.json -> report.html + summary.md
  317. scripts/tracekit/ the logic, one concern per module (raises InvestigateError instead of exiting)
  318. errors.py jsonio.py InvestigateError; load_json / write_json
  319. gitcmd.py Git: running git for one repository
  320. sourcefile.py SourceFile, SourceCache: lines, snippets, enclosing definitions
  321. workspace.py Workspace: the repo + its output folder and meta.json
  322. preparer.py Preparer: resolve targets, create the folder, collect context
  323. target.py TargetResolver: file:line / Class#method / route / text -> candidates
  324. context.py ContextCollector, SourceDocument: bug reports, specs, images, links
  325. stacktrace.py StackTraceParser, FrameMapper, StackTraceDigest
  326. discover.py AppDiscovery, FileCategorizer, TestRunnerFinder
  327. stacks.py StackDetector: languages and frameworks from manifests
  328. dbconfig.py DbConfigReader: DB settings, credentials redacted
  329. dbsafe.py SqlGuard (single read statement + LIMIT), DatabaseUrl (local only)
  330. dbrunner.py QueryRunner: SqliteRunner, PostgresRunner, MysqlRunner (read-only sessions)
  331. masking.py RowMasker: secrets redacted, personal data masked
  332. records.py RecordRef, SchemaIntrospector, RecordGraph: reference data via FKs / *_id
  333. tracelog.py TraceLog (load, compact), TraceDigest (readable timeline)
  334. renderer.py Renderer, RenderResult: validate + build the report and summary
  335. vocabulary.py the enums of investigation.json
  336. validator.py InvestigationValidator
  337. snippets.py SnippetCollector: source code embedded in the report
  338. summary.py SummaryWriter: the markdown summary posted in the chat
  339. report.py ReportBuilder: template + embedded JSON
  340. ```
  341. The tracers are classes too: `AppFiles`, `ValueFormatter`, `Snapshotter`, `EventLog`, `LibraryProbe`, `NetworkGuard`, `Sandbox`, `TraceApi`, `Recorder` and `TraceRunner` in Python, and the matching classes in Ruby (including `NetworkGuard` and `Sandbox`). Each stays a single file, so it runs under your project's interpreter without installing anything.
  342. Syntax highlighting loads highlight.js from cdnjs. Without internet the report still works, just without colours.
  343. ## Related
  344. - [claude-code-review](https://github.com/rewin0087/claude-code-review): `/branch-review`, AI code review of your branch's changes with an interactive HTML diff report.
  345. ## Contributing
  346. Issues and pull requests are welcome. If `/investigate` helped you find a bug, a ⭐ on GitHub helps other developers find it.
  347. See [CHANGELOG.md](CHANGELOG.md) for release notes.
  348. ## License
  349. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.