Investigate a specific problem and produce a structured fix-path document saved to the project's docs/inspections/ directory.
Trigger: when the user asks "how should I fix X", "what are my options for Y", "investigate Z before I touch it", or triggers directly via /create-inspection. Also useful before invoking the /fix-with-evidence skill to pre-evaluate approaches.
Arguments: $ARGUMENTS — a description of the problem or subject to inspect (e.g. "auth token refresh race condition", "N+1 queries in /api/dashboard", "flaky E2E login test"). Required — if empty, ask the user.
Purpose
/create-inspection is not an audit (it doesn't enumerate all issues) and not a fix (it doesn't implement anything). Its output is a decision document: here is what is broken, here are the viable paths to fix it, here is a recommended approach with rationale. Sits between the /create-audit skill (find problems) and the /fix-with-evidence skill (implement the fix).
Steps
Parse the subject from $ARGUMENTS. If empty or vague, ask the user to describe the symptom or problem.
Locate the problem in the codebase. Use Grep, Glob, and Read to find the relevant files, functions, configs, and tests. Do not guess — verify every claim with a file:line citation.
Diagnose root cause. Read enough code to understand why the problem occurs, not just where. If there are tests, run them to observe the failure. If the issue is behavioural (performance, flakiness), read logs or run diagnostic commands.
Generate at least 2 fix options. For each option:
- Describe the approach concisely
- List the files/components touched
- State the trade-offs (complexity, blast radius, test surface, reversibility)
- Estimate effort:
low (< 1 hr), medium (1–4 hrs), high (> 4 hrs)
- Assess risk:
low, medium, high
Pick a recommended option and explain why it best balances correctness, risk, and effort. If options are genuinely tied, say so and flag the deciding factor for the user.
Generate the inspection document with this structure:
# Inspection: <Subject> — <YYYY-MM-DD>
<One-sentence description of the problem and its impact.>
## Root Cause
<Evidence-backed explanation of why the problem occurs. Include file:line citations.>
## Scope
Files and components relevant to this problem.
| File / Component | Role in the problem |
| ---------------- | ------------------- |
| ... | ... |
## Fix Options
### Option 1: <Name>
**Approach:** <description>
**Files touched:** <list>
**Effort:** low | medium | high
**Risk:** low | medium | high
**Trade-offs:** <pros and cons>
### Option 2: <Name>
...
## Recommendation
**Use Option N: <Name>**
<2-3 sentences explaining why this option is best for the current situation.
Call out any assumptions (e.g. "assumes test coverage exists for the path").>
## Next Step
Run `/fix-with-evidence <subject>` using the recommended option,
or proceed manually using the approach above.
Generate a filename in the format: <topic-slug>-<YYYY-MM-DD>.md (e.g. auth-refresh-race-2026-04-14.md). Use lowercase kebab-case.
Write the file to docs/inspections/<filename>. Create the docs/inspections/ directory if it doesn't exist.
Report to the user: show the file path, the root cause in one sentence, and the recommended option. Do not dump the full document into chat.
Rules
- Every root-cause claim must be backed by a
file:line citation or command output. No assumptions.
- Always provide at least 2 distinct fix options. Single-option "inspections" are just instructions.
- Never implement a fix. Surface options and recommend. The user decides.
- Do not commit the inspection file. Leave it untracked for the user to review.
- If the problem cannot be localized (e.g. no repro, insufficient context), state that clearly and list what additional information is needed rather than producing a speculative document.
- Keep the document concise. Tables over prose where possible. No filler.
1---2name: create-inspection3description: Investigate a specific problem and surface viable fix paths with trade-offs, saved to docs/inspections/. Triggers on: "how should I fix", "what are my options", "investigate before I touch".4---56Investigate a specific problem and produce a structured fix-path document saved to the project's `docs/inspections/` directory.78Trigger: when the user asks "how should I fix X", "what are my options for Y", "investigate Z before I touch it", or triggers directly via `/create-inspection`. Also useful before invoking the `/fix-with-evidence` skill to pre-evaluate approaches.910Arguments: `$ARGUMENTS` — a description of the problem or subject to inspect (e.g. "auth token refresh race condition", "N+1 queries in /api/dashboard", "flaky E2E login test"). Required — if empty, ask the user.1112## Purpose1314`/create-inspection` is **not** an audit (it doesn't enumerate all issues) and **not** a fix (it doesn't implement anything). Its output is a **decision document**: here is what is broken, here are the viable paths to fix it, here is a recommended approach with rationale. Sits between the `/create-audit` skill (find problems) and the `/fix-with-evidence` skill (implement the fix).1516## Steps17181. **Parse the subject** from `$ARGUMENTS`. If empty or vague, ask the user to describe the symptom or problem.19202. **Locate the problem in the codebase.** Use `Grep`, `Glob`, and `Read` to find the relevant files, functions, configs, and tests. Do not guess — verify every claim with a `file:line` citation.21223. **Diagnose root cause.** Read enough code to understand _why_ the problem occurs, not just _where_. If there are tests, run them to observe the failure. If the issue is behavioural (performance, flakiness), read logs or run diagnostic commands.23244. **Generate at least 2 fix options.** For each option:25 - Describe the approach concisely26 - List the files/components touched27 - State the trade-offs (complexity, blast radius, test surface, reversibility)28 - Estimate effort: `low` (< 1 hr), `medium` (1–4 hrs), `high` (> 4 hrs)29 - Assess risk: `low`, `medium`, `high`30315. **Pick a recommended option** and explain why it best balances correctness, risk, and effort. If options are genuinely tied, say so and flag the deciding factor for the user.32336. **Generate the inspection document** with this structure:3435 ```markdown36 # Inspection: <Subject> — <YYYY-MM-DD>3738 <One-sentence description of the problem and its impact.>3940 ## Root Cause4142 <Evidence-backed explanation of why the problem occurs. Include file:line citations.>4344 ## Scope4546 Files and components relevant to this problem.4748 | File / Component | Role in the problem |49 | ---------------- | ------------------- |50 | ... | ... |5152 ## Fix Options5354 ### Option 1: <Name>5556 **Approach:** <description>57 **Files touched:** <list>58 **Effort:** low | medium | high59 **Risk:** low | medium | high60 **Trade-offs:** <pros and cons>6162 ### Option 2: <Name>6364 ...6566 ## Recommendation6768 **Use Option N: <Name>**6970 <2-3 sentences explaining why this option is best for the current situation.71 Call out any assumptions (e.g. "assumes test coverage exists for the path").>7273 ## Next Step7475 Run `/fix-with-evidence <subject>` using the recommended option,76 or proceed manually using the approach above.77 ```78797. **Generate a filename** in the format: `<topic-slug>-<YYYY-MM-DD>.md` (e.g. `auth-refresh-race-2026-04-14.md`). Use lowercase kebab-case.80818. **Write the file** to `docs/inspections/<filename>`. Create the `docs/inspections/` directory if it doesn't exist.82839. **Report to the user**: show the file path, the root cause in one sentence, and the recommended option. Do not dump the full document into chat.8485## Rules8687- Every root-cause claim must be backed by a `file:line` citation or command output. No assumptions.88- Always provide at least 2 distinct fix options. Single-option "inspections" are just instructions.89- Never implement a fix. Surface options and recommend. The user decides.90- Do not commit the inspection file. Leave it untracked for the user to review.91- If the problem cannot be localized (e.g. no repro, insufficient context), state that clearly and list what additional information is needed rather than producing a speculative document.92- Keep the document concise. Tables over prose where possible. No filler.
kaiohenricunha