--- name: dissect description: >- Evidence-driven dissection of an existing service, written plan, or codebase area. Interrogates every entity (table, field, component, endpoint, module, boundary) against ground truth from multiple sources at once, red-teams each verdict devil's-advocate style, and arrives at the minimal-build optimization plan. Runs as a staged pipeline with human checkpoints and parallel read-only sub-agents so each investigation stays laser-focused. Optional --circuit skips intermediate checkpoint waits and asks at the final recommendation; --autopilot takes recommended choices and proceeds. Use when the user invokes /dissect, or asks to audit / optimize / challenge / "tear apart" an existing system, schema, or plan. If the session is in Cursor or Claude Plan Mode, update the existing plan in place — never rewrite it. Use inception to author a new plan. user-invocable: true disable-model-invocation: false version: "2.6.0" author: "Ali Farahat" tags: ["dissect", "audit", "red-team", "minimal-build", "refactor", "ground-truth", "orchestration"] when_to_use: | USE WHEN (backward-looking, "what is actually here and what should change?"): - User invokes /dissect or asks to audit, dissect, optimize, or challenge an EXISTING service, schema, data model, or codebase area. - User hands you a WRITTEN PLAN or spec and wants it pressure-tested against the code/DB that already exists (intent vs reality). - A system feels bloated, over-engineered, or misnamed and you need an evidence-backed keep/fold/drop/defer decision per entity. - You suspect scope-creep, dead code, stubs masquerading as features, or tables/ components living in the wrong domain. - Before a migration or refactor, to find the minimal set of changes that actually meets the requirement. - The session is in Cursor Plan Mode or Claude Plan Mode and the user wants the current plan dissected, fixed, and tuned (gaps filled, errors corrected) without replacing the document. DO NOT USE WHEN: - The thing does not exist yet and you need a detailed work-breakdown plan. That is `inception`. If you only need to pick among approaches, use `deep-deliberation`. - The task is a quick lookup or a one-line fix with an obvious answer. - You only have intent (a plan) with no code/DB/runtime to verify against AND no way to get ground truth — dissect's power comes from live evidence; flag the gap. --- # Dissect > **Leading words:** dissect, ground truth, entity-level, minimal-build, > red-team, evidence-backed, stub detection, naming audit, fold test, > phase separation, patch in place, circuit, autopilot, plain question. Systematically interrogate and optimize an existing service, written plan, or system. The goal is not to rubber-stamp the current design — it is to arrive at the **minimal-build plan** that correctly meets the requirements, by challenging every assumption with live evidence and an adversarial review panel. **Trigger:** `/dissect [--circuit|--autopilot] ` where `` is a service name, plan file path, codebase area, or free-form description. If omitted, ask. Pace flags are optional; default is interactive (stop at every checkpoint). `dissect` is the backward-looking counterpart to `deep-deliberation`. They share DNA — parallel read-only sub-agents, devil's-advocate red-teaming, human checkpoints, evidence over intent, and the same `--circuit` / `--autopilot` grammar — but point in opposite directions: deliberation designs what to build; dissect audits what already exists. --- ## User Input ```text $ARGUMENTS ``` Parse a pace flag from arguments **before** treating the rest as ``: `--circuit`, `--autopilot`, `--auto` (alias of `--autopilot`). Strip the flag from the target string. If both circuit and autopilot appear, autopilot wins. --- ## Pace modes (optional) Default is **interactive**: stop and wait at every checkpoint. The user must opt in **this invocation** — a flag above, or an explicit phrase (`circuit`, `autopilot`, `take recommended`, `circuit the rest`, `autopilot the rest`). Do not infer from urgency, "just audit this", or a desire to move fast. Mid-run, the same phrases switch mode from the current checkpoint. `stop circuit` / `stop autopilot` drops back to interactive. | Mode | Intermediate checkpoints (1–2) | Final checkpoint (3) | |---|---|---| | `interactive` | Stop and wait | Stop and wait. Do not proceed until they ask | | `--circuit` | Auto-accept the recommended choice; log and continue | Stop. Ask whether to go ahead with the final recommendation | | `--autopilot` | Auto-accept; log and continue | Auto-accept. Treat the recommendation as the way to proceed | **Skip the wait, not the work.** Stages, evidence, red-team, and the naming audit still run. Emit a compact `PACE_LOG` of every auto-accepted choice. **Cannot proceed:** if there is no unique recommendation (tie, empty shortlist, pipeline wants to go backward), stop and ask even on autopilot. **Proceed** (autopilot, or circuit after the user says go ahead): - Plan Mode / existing plan file: apply the surgical patch map. Do not implement code unless they also asked to implement. - Otherwise: start executing the recommended ToT / execution branch. Discrepancies still surface (principle 9). Circuit holds them for the final ask. Autopilot logs the recommended resolution in `PACE_LOG` and the report; never drop them. **Interactive final footer.** On Checkpoint 3 only, when this run is interactive, append the block below **verbatim as the last thing in the message** (after the Checkpoint 3 ask). Omit it under `--circuit` / `--autopilot`. Do not paraphrase. Do not place it earlier. ```markdown ⚡ **Skip the waits next time** This run was **interactive** — a stop at every checkpoint. Same skill, two other paces: - `--circuit` — take the recommended choices through the middle checkpoints, then stop at the final recommendation and ask before proceeding. - `--autopilot` — take every recommended choice, including the last, and proceed without waiting. `/dissect --circuit ` · `/dissect --autopilot ` ``` --- ## User questions (plain question) The report may be technical. The **ask** must not be. Same turn as the checkpoint message: host structured question tool (Cursor `AskQuestion`, Claude Code `AskUserQuestion`, OpenCode equivalent). No tool → numbered list. Do not replace the report. Then stop. Prompt: one sentence, product language. Labels ≤40 chars. First ends `(Recommended)`. Last is always `Say this in plain English` (meta: do not advance; rephrase + one example of what each real option means here; re-ask). Second pick: a simpler analogy. Free-text overrides. Per-option descriptions: one plain sentence if the host supports them. Any ask to the human (including cannot-proceed) follows this contract. --- ## Core principles (never waive) 1. **Ground truth beats intent.** What the code actually does overrides what the plan says it should do. Always verify live. 2. **Row counts are a liveness signal only.** A 0-row table can be load-bearing; a populated table can be redundant. Never use row count as a keep/drop reason. 3. **Name what it IS, not what it was named.** Entities are frequently misnamed. Read a few actual records before drawing conclusions. A table called `contact_preference` might store food allergies and golf equipment. 4. **Own vs read.** "Entities this service reads" ≠ "entities this service owns." Reading a table does not mean you should count it in the domain. 5. **Stubs are not live.** A function that `throws new Error('not implemented')`, a cron that no-ops, or a consumer that re-queues to the DLQ is not a running feature. Check before counting it as active behavior. 6. **Minimal build.** Every proposed change must trace to a requirement. Do not design for hypothetical future use. Three similar things beat a premature abstraction. 7. **Naming audit is phase zero.** Naming confusion causes the most incorrect verdicts. Run it before any verdict. 8. **Sub-agents return evidence, the orchestrator returns verdicts.** A sub-agent that declares "VERDICT: DROP" unprompted is overstepping. Synthesis happens in the main context where all evidence is held together. 9. **Escalate discrepancies, don't resolve them silently.** If code says X and the plan says Y, surface both. Interactive: wait at the checkpoint. `--circuit`: hold them for the final ask. `--autopilot`: log the recommended resolution in `PACE_LOG` and the report; never drop them. 10. **Patch in place — never rewrite the live plan.** If the session is in Cursor Plan Mode or Claude Plan Mode, or the target is an existing plan document, the source plan is the document of record. Dissect it, then surgically update it (fix, tune, fill gaps). Never full-file `Write` it. Never create a second plan that replaces it. Unaddressed sections stay verbatim. Read [references/plan_preservation.md](references/plan_preservation.md) before any write. Override only if the human explicitly asks to rewrite from scratch. --- ## Pipeline overview ``` USER input (service / plan / codebase area) ↓ [Stage 0] Intake + Naming Audit (1 explore sub-agent) 🛑 CHECKPOINT 1 — human confirms names + scope boundary ↓ [Stage 1] Multi-source Ground Truth (3 explore sub-agents, parallel) [Stage 2] Entity-level Devil's Advocate (1 explore sub-agent per cluster) 🛑 CHECKPOINT 2 — human reviews per-entity verdicts ↓ [Stage 3] Cross-cutting + Adversarial Red-Team (system challenge + ToT branches) [Stage 4] Synthesis + Minimal-Build Plan (orchestrator, main context) 🛑 CHECKPOINT 3 — human picks the execution branch ``` Copy this checklist and track progress out loud: ``` Progress: - [ ] Stage 0: Naming audit - [ ] CHECKPOINT 1 — names + scope confirmed - [ ] Stage 1: Multi-source ground truth (DB + code + plan, parallel) - [ ] Stage 2: Entity-level devil's advocate (one agent per cluster) - [ ] CHECKPOINT 2 — entity verdicts reviewed - [ ] Stage 3: Cross-cutting challenges + ToT refactor branches + red-team - [ ] Stage 4: Synthesis → minimal-build plan - [ ] CHECKPOINT 3 — execution branch chosen ``` > **Right-size the pipeline.** This is heavy. For a small target (a handful of > entities, one file) collapse Stages 0–2 into a single pass and skip the parallel > fan-out — but never skip the naming audit. Checkpoint 1 **wait** is skippable > only under `--circuit` / `--autopilot`. --- ## Stage 0 — Intake + Naming Audit Surface naming confusion that could corrupt every later verdict, before any analysis. Dispatch one read-only (`explore`) sub-agent: ``` Prompt: Naming audit for . For every entity (table, field, service, component, endpoint) in scope: 1. Does the name accurately describe what it actually holds/does? 2. Is there another entity with a similar name it could be confused with? 3. Read 2–3 actual records (or the code body) and compare to the name. Flag any mismatch. Return a table only (no verdicts): Entity | What name implies | What it actually contains | Mismatch? ``` If the session is already in **Cursor Plan Mode** or **Claude Plan Mode** and the user did not name a different target, the target **is the current plan document**. Record its path. Read [references/plan_preservation.md](references/plan_preservation.md) now — before any write. ### 🛑 Checkpoint 1 Lead with one sentence a product owner could repeat (what you found, what's in vs out of scope). Then the naming table and proposed scope boundary (what this target owns vs merely reads). Interactive: structured question per **User questions**, then stop. ```text prompt: Some names don't match what they actually store. Use the corrected names for the rest of this review? options: - Yes, use the corrected names (Recommended) - Keep the original names - Change what we're reviewing first - Say this in plain English ``` `--circuit` / `--autopilot`: log the proposed names and scope as auto-accepted (`PACE_LOG`) and continue. A mismatch here changes the verdicts in every later stage. --- ## Stage 1 — Multi-source Ground Truth Gather evidence from **all three** sources simultaneously via parallel read-only sub-agents. Each source catches what the others miss. | Source | What it catches | |---|---| | **Live DB / runtime** | Actual schema, real data, column comments, row shapes | | **App code** | What actually reads/writes each entity; stubs vs live paths | | **Plan / spec / migrations** | Intent; evolution history; documented decisions | Launch three `explore` sub-agents in parallel (one message, three `Task` calls): **A — Live introspection:** every in-scope entity (name, fields, types, descriptions), 2 sample records each, row counts (liveness only), and FK/ownership relationships. **B — Code evidence:** every file that reads/writes each entity (file:line); whether each reader/writer is live or a stub; the module that OWNS each entity vs those that merely READ it; any code using the wrong entity for its purpose. **C — Plan / spec / migration evidence:** the original design doc, migration history (before/after), documented decisions, what was explicitly deferred or descoped, and what the plan SAYS is live vs what code/DB show. Synthesize the three outputs. Note every discrepancy between sources — that is where the real problems live. --- ## Stage 2 — Entity-level Devil's Advocate For each entity **cluster** (group related entities), dispatch one focused `explore` sub-agent that challenges every verdict. **One cluster = one agent.** Never batch unrelated clusters — context pollution corrupts both verdicts. Standard question set (apply to every entity): ``` For entity : 1. PURPOSE — Plain terms: what does it do? What breaks if it vanished tomorrow? 2. OWNERSHIP — Does own it, or merely read it from another domain? 3. NAME — Does the name match the data? (Reference Stage 0.) 4. EVIDENCE — Live code that reads AND writes it? file:line each. Writers but no readers (or vice-versa) → flag. Read by a service that shouldn't own it → flag. 5. FOLD TEST — Can it be absorbed into a parent? (See fold tests below.) 6. PII/BOUNDARY — Personal data? Which DB/domain should it live in? Match current? 7. STUB CHECK — Is the using code live, or a stub/throw/no-op? 8. VERDICT — Propose from the dynamic taxonomy below, justified with evidence. Never justify with row count. ``` ### 🛑 Checkpoint 2 Lead with one sentence a product owner could repeat. Then the per-entity verdicts table (Entity | Proposed verdict | Evidence). Interactive: structured question per **User questions**, then stop. ```text prompt: For each piece I recommend keep it, combine it, remove it, or move it. Look right? options: - Looks right, keep going (Recommended) - I want to change some of those - Look closer at one of them - Say this in plain English ``` `--circuit` / `--autopilot`: log the proposed verdicts as auto-accepted and continue. --- ## Dynamic verdict taxonomy `KEEP / FOLD / DROP` is too rigid — it only fits relational tables. A dissection target may be a written plan, a runtime flow, or a coupled module, so verdicts are **action-oriented and target-aware**. The full taxonomy (KEEP, FOLD, DROP, DEFER, ON-DEMAND, EXTRACT, RE-HOME, REFACTOR, OUT-OF-SCOPE) with meanings, plan-vs-code typicals, and the distinctions that matter (RE-HOME vs EXTRACT, DEFER vs DROP, ON-DEMAND vs KEEP) lives in [references/verdict_taxonomy.md](references/verdict_taxonomy.md). Each verdict must cite evidence (file:line or live DB), never row count. Pick the most precise verdict from the taxonomy. --- ## Stage 3 — Cross-cutting challenges + adversarial red-team After entity verdicts, challenge the **system-level design**, then red-team the emerging plan from independent adversarial angles. This is where dissect borrows deep-deliberation's Tree-of-Thought and red-team machinery. ### 3a. System-level questions (one `explore` sub-agent) 1. **Send/process model** — Is there pre-staging/pre-rendering/pre-computation that could be deferred to the moment it's needed? What's the throughput ceiling? 2. **Feedback loops** — When something fails (bounce, rejection, error), is the signal captured and acted on, or is the feedback path a stub? 3. **Ownership boundaries** — Where does this service read/write data that belongs to another? Any misuse of another domain's tables? 4. **Naming & taxonomy** — Are concepts that share a name actually different things (kind vs channel vs group)? Conflation causes the worst bugs. 5. **Live vs designed** — For each major feature, is it actually running or a stub/planned/throw? List what is NOT live that the plan implies is live. ### 3b. Tree-of-Thought refactor branches (orchestrator) Do not assume a single target state. Generate **2–4 distinct end-states** for the optimization, each with idea, pros/cons, main risk, and rough effort (S/M/L). Example axis for a storage-heavy target: - *Branch A — ON-DEMAND:* compute at read, zero new storage. - *Branch B — FOLD/JSONB:* absorb into parent, flexible, fewer joins. - *Branch C — hard relational consolidation:* columns + strict keys. Prune dominated branches and say why. Recommend one + a runner-up. ### 3c. Adversarial red-team panel (parallel `explore` sub-agents) Launch independent personas in parallel; each attacks first, then concedes what survives, and returns evidence — not a final verdict. Minimum panel: - **Zero-Utility Hawk** — argues to DROP or FOLD every entity; forces each KEEP to earn its place against live evidence. - **Migration-Risk Hawk** — red-teams the proposed plan itself: does the migration create more downtime/risk than leaving the mess in place? - **Boundary Hawk** — hunts ownership/PII violations and wrong-domain reads. - **Stub Hunter** — proves which "features" are actually live vs throws/no-ops/DLQ. (Reuse the deep-deliberation persona prompt shape: identity → relevant file paths → approach under review → attack, then concede, then evidence.) ### 3d. Lead judgment (orchestrator) After the panel returns, you are the lead. Filter findings before they enter Stage 4. Do not auto-apply. | Bucket | Meaning | |---|---| | **Act On** | Consensus or a lone finding with a `file:line` that would ship a real defect | | **Consider** | Plausible, not proven; mention in the report | | **Noted** | Style or preference; do not churn the plan | | **Dismissed** | Nit, hypothetical, or "I would have done it differently" with no failure | Nitpick gravity: a rename is not a defect. Hypothetical vs actual: "could theoretically" without a path is Dismissed. Preserve material disagreements; never silently average them away. --- ## Stage 4 — Synthesis + minimal-build plan Done in the main context (synthesis needs all evidence held together). Output: **0. Naming corrections** — every mismatch found, with corrected names (apply throughout). **1. Scope boundary corrections** — entities wrongly counted in this domain; the real owner of each; any live code that incorrectly crosses the boundary. **2. Entity verdicts** — one table: Entity | Verdict | Rationale (file:line / live evidence) | Lands (if FOLD/RE-HOME). No row-count justifications. **3. System-level changes** — for each cross-cutting issue, in this format: - **Decision:** [what] - **Why:** [evidence-backed reason] - **Other options:** [alternatives + why rejected] **4. Bug / misuse log** — places where code uses the wrong entity or wires an entity to the wrong system. Correctness issues, distinct from optimization. **5. Execution order** — the minimal-build sequence: highest-value/most-independent first, what depends on what, what to defer. **6. Deferred / out of scope** — what is intentionally NOT changing, each with a reason. The six sections above are the **dissection report** (chat). They are not a replacement body for an existing plan file. ### Plan Mode / existing plan document If the session is in Cursor or Claude Plan Mode, or the target is an existing plan file: do **not** emit a new plan. Follow [references/plan_preservation.md](references/plan_preservation.md). Build a patch map (`KEEP` / `PATCH` / `APPEND` / `FLAG`), apply surgical edits after Checkpoint 3, and preserve every unaddressed section. `APPEND` is how newly identified gaps land in the plan — they are added, not used as a reason to rewrite. ### 🛑 Checkpoint 3 Lead with one sentence a product owner could repeat. Then the technical detail (recommended ToT branch and ranked alternatives). If a live plan is being patched, also present the patch map. Interactive / `--circuit`: structured question per **User questions**, then stop. Name the recommended branch in the prompt in product language, not taxonomy. ```text prompt: I recommend we do “[short name]”: [one-line why]. Go with that? options: - Yes, do that (Recommended) - Do the other option instead - Don't start yet - Say this in plain English ``` - **Interactive:** do not start implementing unless they ask. Do not touch the plan file until they confirm. End the message with the interactive final footer (Pace modes) — last block, verbatim. - **`--circuit`:** if they say no, stay at this checkpoint. - **`--autopilot`**, or **circuit after they say go ahead:** proceed as defined under Pace modes. --- ## Fold tests (reference) The full fold-test table (cardinality → fold type → blocker, plus the independent-relational-access check and the PII/DB-boundary rule) lives in [references/fold_tests.md](references/fold_tests.md). Quick reference: - 1:1 with parent → columns on parent (just do it). - 1:N bounded (≤~10) → JSONB on parent, **unless** independent relational access is needed. - 1:N unbounded/queried, N:M → keep as table. - Never fold across a PII/DB boundary. --- ## Sub-agent dispatch rules - **Parallel for the Stage 1 triple** (DB + code + plan) — independent, run at once. - **One cluster per Stage 2 agent** — never mix unrelated clusters. - **Read-only only.** All dissection agents use `subagent_type: "explore"`. No write access. Do NOT pass a `model` — sub-agents inherit the parent model. - **Agents return raw evidence, not verdicts.** Synthesis is the orchestrator's job. Escalate discrepancies to the checkpoint (or `PACE_LOG` / final ask under pace modes); never drop them. --- ## Key lessons (baked in) - **Read the actual data first.** A table named `managed_preference` might contain "Favorite Drink → Moscow Mule." You would never know without reading it. - **Channel ≠ kind ≠ group.** Multiple orthogonal taxonomies get conflated; that produces wrong verdicts. Keep them distinct. - **"Built for" vs "used for."** A table built for one purpose can be misused for another. If design intent and actual use diverge, that's a bug, not a design. - **The eligibility/read pipeline is not authoritative.** What a pipeline reads doesn't define the correct data model — it may be reading the wrong thing. - **Stubs inflate the system.** A cron that throws, a consumer that re-queues, a client that returns `permanent_failure` for all inputs — none are live. - **Plan and code diverge.** The plan is intent; the code is reality. Ground the optimization in reality. --- ## Output format notes - Every verdict cites evidence. No bare assertions. - Every FOLD/RE-HOME states the target it lands in and which fold test applies. - Every OUT-OF-SCOPE names the correct domain owner. - Every DROP names the reason (no code path / derivable / moved / legacy). - Every DEFER/ON-DEMAND names the requirement that justifies the seam (or its absence). - Row count appears only as liveness context, never as a reason. - Lead with plain-terms summaries, then technical detail. Write both. The structured question at each checkpoint is a **plain question** (User questions); jargon stays in the report, not in the prompt or labels. - Interactive Checkpoint 3: end with the pace-mode footer from Pace modes (verbatim, last block). Omit under `--circuit` / `--autopilot`. ## References | File | Use it for | |---|---| | [references/verdict_taxonomy.md](references/verdict_taxonomy.md) | Full dynamic verdict taxonomy (KEEP/FOLD/DROP/DEFER/ON-DEMAND/EXTRACT/RE-HOME/REFACTOR/OUT-OF-SCOPE) with meanings, plan-vs-code typicals, distinctions, output format | | [references/fold_tests.md](references/fold_tests.md) | Fold-test table (cardinality → fold type → blocker), independent-relational-access check, PII/DB-boundary rule | | [references/plan_preservation.md](references/plan_preservation.md) | Plan Mode / existing plan file: patch in place, never rewrite. Detection, forbidden actions, patch map, host notes, worked example |