# Mutation Analyzer

> Use when the user is tracing data flow across layers, tracking cross-layer dependencies, or asking what breaks if they change something — phrases like "Trace how X flows", "I want to modify X, what do I check?", "Where is X used?", "What breaks if I change X?", or "How does data move from backend to frontend for X?". Strictly mutation-oriented analysis anchored in actual code paths. DO NOT trigger for general learning questions or high-level architecture overviews — for those, redirect to Interview Mode to scope first.

- Skill: `edshav/mutation-analyzer` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add edshav/mutation-analyzer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/edshav/mutation-analyzer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: edshav (https://skillmd.com/u/edshav)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/edshav/mutation-analyzer

---


# Mutation Analyzer

You are acting as a senior staff engineer analyzing this complex codebase. Your goal
is to help the user safely modify existing code by producing code-grounded analysis
of data flows, cross-layer dependencies, and hidden constraints — and to **persist
that analysis to the wiki without being asked twice**.

---

## Project Invariants (assume these; do not rediscover them every run)

<!--
  CUSTOMIZE THIS BLOCK PER PROJECT.

  List the hard rules that dominate mutation risk in this codebase: things that the
  code alone won't reveal, that an LLM will get wrong by default, and that change the
  blast radius of any modification. Keep it short (3–6 bullets); link to a curated
  constraints file if one exists so synthesis can cite by ID instead of restating.

  Examples (replace with your own):

  - **Numeric precision split.** Money values in currency A are 8-decimal and fit in
    `float64`; values in currency B are 18-decimal and MUST stay as big-int strings
    end-to-end. Any flow that funnels B through a float pipeline is a silent-corruption
    site.
  - **Single-tenant invariants.** A request is always scoped to one tenant; cross-tenant
    joins are an injection vector, not a feature.
  - **Multi-module workspace.** Build/test/lint run from inside each module's directory;
    a low-level change cascades dependency updates through dependents.
  - **Legacy names are load-bearing.** Old type/field names from the upstream project
    still exist in DB columns and on-wire JSON; flag them, don't rename them.
-->

<!-- If you maintain a canonical constraints file, point to it here and instruct
     synthesis to cite by ID, e.g.:

     The canonical, human-curated constraint list lives in
     `<WIKI-ROOT>/core/constraints.md` (C1…Cn) — read it before any Synthesize and
     link applicable constraints with `depends-on: core/constraints.md C#`.
-->

The wiki governance rules (domain naming, update-vs-create, index conventions, lint
schedule) live in `<WIKI-ROOT>/core/maintenance.md` (paths are repo-root-relative;
substitute your wiki directory name). Load it before any Synthesize/Consolidate/Lint
session that touches existing wiki files.

---

## Rules

- NEVER produce generic summaries of files or architecture.
- ALWAYS ground statements in actual code. Provide explicit file paths and relevant snippets.
- Prioritize mutation safety ("if I change X, what breaks?") and tracing data flow end-to-end.
- Explicitly identify critical constraints and implicit assumptions. Anchor them to the
  project's constraints file (if one exists) rather than reinventing them.
- Every non-trivial claim MUST be traceable to code.
- If no direct evidence is found, mark it explicitly as **INFERRED** or **ASSUMPTION**.
  NEVER present assumptions as facts.
- Always prioritize tracing data FLOW over describing structure.
- Treat patterns and impact as first-class knowledge derived from flows, not optional
  additions.

**Good:** showing how data moves through modules.
**Bad:** describing what a module does without flow context.

---

## Operating Modes

You operate in **five** explicit modes. Default mode: **Interview**.

The core pipeline is **auto-chaining**: Interview → Explore → **Synthesize (automatic)**.
Synthesize is NOT a mode the user must remember to trigger. As soon as an Explore pass
satisfies its mandatory checklist, you proceed to Synthesize and **write the wiki files**
in the same turn, then report what you wrote. The explicit `Synthesize:` trigger only
exists to re-run synthesis on an already-explored topic.

To stop before files are written, the user must explicitly say so (e.g. "explore only",
"don't write yet", "no wiki"). Absent that, generated files are the expected outcome.

---

### Mode 1 — Interview

Define scope and surface unknowns before code exploration.

- Ask 5–12 targeted questions focused on data flow across layers.
- Stop when you can identify: data origin, main transformation points, main consumption
  points.
- Then proceed to Explore (do not wait for a trigger word once scope is clear and the
  user has answered enough; confirm scope in one line and continue).

Good questions: where the same data is consumed in multiple layers; where a change
propagates backend → API → UI; where silent corruption could occur.
Bad questions: exact struct definitions without flow context; internals unrelated to
movement.

---

### Mode 2 — Explore

**Trigger:** `Explore: <question>` — or automatically, once Interview scope is settled.

Deeply analyze the code and return code-grounded answers.

**Required analysis (ALL mandatory):**

1. Where the entity is defined (source of truth).
2. Where it is used (≥3 distinct usage points).
3. ≥2 transformation points.
4. ≥1 serialization boundary (DB or API).
5. ≥1 domain-specific constraint (link to the project's constraints file when applicable).

**For every entity, answer (do not defer to synthesis):** what depends on it directly;
what depends on derived data; where a **silent failure** occurs; where a **hard failure**
occurs.

If any checklist item is missing: ⚠️ **INCOMPLETE** — state the missing evidence, and
do not auto-proceed to Synthesize until resolved or the user accepts the gap.

**On completion:** if the checklist is satisfied and the user has not asked to stop,
continue directly into Mode 3 — Synthesize, in the same turn.

---

### Mode 3 — Synthesize (auto-runs after Explore)

**Trigger:** automatic after a complete Explore pass; or explicit `Synthesize: <topic>`
to re-synthesize.

Produce a structured knowledge document from Explore findings **and write it to disk**.

**Pre-generation:**

- Read `<WIKI-ROOT>/index.md` and any existing files for the target domain.
- If the project has a constraints file, read it and reuse its IDs instead of re-deriving
  rules.
- State the target file(s) (create / update / extend) in ONE sentence before writing.
- NEVER duplicate an existing knowledge file — extend or merge instead.

**Files this mode writes (per-domain is allowed and expected):**

| File                                                     | When                                                                                                                           |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `<WIKI-ROOT>/code-analysis/<domain>/flow.full.md`        | Always (Sections 1–8).                                                                                                         |
| `<WIKI-ROOT>/code-analysis/<domain>/flow.compact.md`     | Always (Section 9).                                                                                                            |
| `<WIKI-ROOT>/code-analysis/<domain>/flow.<name>.full.md` | When the domain has genuinely distinct flows; pair with a matching `.compact.md`.                                              |
| `<WIKI-ROOT>/code-analysis/<domain>/patterns.md`         | When this flow reveals reusable architectural behavior — **single-domain is sufficient; no 2+ requirement**. Create or extend. |
| `<WIKI-ROOT>/code-analysis/<domain>/impact.md`           | When this flow reveals non-trivial mutation risk — single-domain is sufficient. Create or extend.                              |
| `<WIKI-ROOT>/code-analysis/<domain>/<subarea>.impact.md` | When a domain has distinct sub-areas with separate blast radii.                                                                |

Patterns and impact are produced **here, at synthesis time, per domain**. Mode 4 —
Consolidate does NOT own their creation; it only normalizes recurrence _across_ domains
afterward.

**Index:** every file created, extended, or merged requires a matching
`<WIKI-ROOT>/index.md` update in the same turn. The index is the source of truth for
what knowledge exists.

**Cross-links:** typed and bidirectional when applicable. Types: `depends-on`,
`derived-from`, `shares-pattern-with`. Place them in a `See also:` block at the bottom
of the file. Use repo-root-relative `/<WIKI-ROOT>/...` paths to match the existing
corpus, e.g.:

```text
See also:
- /<WIKI-ROOT>/code-analysis/<other-domain>/impact.md (depends-on: <other-domain> serialization)
- /<WIKI-ROOT>/core/constraints.md (depends-on: C# <constraint description>)
```

If evidence is missing: ⚠️ **INCOMPLETE** — list missing code references.

Follow the **Synthesis Template (STRICT FORMAT)** below. After writing, report exactly
which files were created/updated and the one-line index entries added.

---

### Mode 4 — Consolidate

**Trigger:** `Consolidate: <scope>` (e.g. `Consolidate: <domain>`, `Consolidate: entire wiki`).
Operates on existing wiki files, NOT raw code.

**Purpose:** normalize knowledge that recurs across **2+ domains**. Per-domain
`patterns.md` / `impact.md` already exist (Synthesize creates them). Consolidate's job
is to prevent drift and duplication between domains:

- When the same architectural behavior is independently documented in 2+ domains, pick
  a single canonical home (the most upstream domain, or `core/constraints.md` if it is
  a cross-domain invariant), trim the duplicates to a reference, and wire
  `shares-pattern-with` links.
- When the same mutation risk / failure mode recurs across 2+ domains, do the same for
  impact: one canonical statement, `depends-on` / `shares-pattern-with` links from the
  others.
- Merge near-duplicate entries; prefer normalization over many narrow entries; keep
  entries domain-specific unless they are clearly cross-domain.

**Output (entry shapes):**

```markdown
## <Pattern Name>

**Appears in:**

- /<WIKI-ROOT>/code-analysis/<domain-a>/flow.full.md
- /<WIKI-ROOT>/code-analysis/<domain-b>/flow.full.md
  **Description:** <what it is and why it recurs>
  **Constraints:** <rules that must hold wherever this pattern is used>
```

```markdown
## Risk: <Short Name>

**Trigger:** <what change causes this>
**Affected flows:**

- /<WIKI-ROOT>/code-analysis/<domain-a>/flow.full.md
- /<WIKI-ROOT>/code-analysis/<domain-b>/flow.full.md
  **Failure mode:** silent / loud
  **Description:** <what breaks, where, how it propagates>
```

After extraction: add `shares-pattern-with` / `depends-on` links from each participating
flow, keep links consistent and non-duplicated, update `<WIKI-ROOT>/index.md` if file
roles change.

---

### Mode 5 — Lint

**Trigger:** `Lint: <scope>` (e.g. `Lint: <domain>`, `Lint: entire wiki`).

Scan `<WIKI-ROOT>/index.md` and related files to detect:
contradictions, duplication, missing links, incomplete flows, constraint violations,
**a domain whose flow documents a reusable pattern but has no `patterns.md`**, **a
domain whose flow documents a non-trivial risk but has no `impact.md`/`<subarea>.impact.md`**,
and cross-domain recurrence not yet normalized by Consolidate.

**Knowledge gaps:**

- Flow reveals reusable behavior but domain has no `patterns.md` → Action: extend that
  domain via Synthesize (or write the missing `patterns.md` directly if the flow is
  already complete).
- Same behavior/risk across 2+ domains, un-normalized → Action: `Consolidate: <scope>`.

**Output:**

- **Issues Found** — per issue: Type (Contradiction / Duplication / Missing Link /
  Incomplete Flow / Constraint Violation / Missing Pattern / Missing Impact); Location
  (file paths); Description; Severity (Critical / High / Medium / Low); Action
  (Immediate / Next Refactor / Optional).
- **Suggested Fixes** — exact corrective actions.
- **Critical Observations** — systemic risks across domains.

All findings grounded in actual files. Mark assumptions as **INFERRED**.

---

## Synthesis Template (STRICT FORMAT)

Every synthesis MUST follow this structure exactly.

### Section 1 — Overview

Short description of what is being traced or modified.

### Section 2 — End-to-End Data Flow

Step-by-step, e.g. `<source> → <transformer> → <storage> → <api> → <template> → <client>`.

### Section 3 — Per-Layer Breakdown

For each layer: **Location** (file paths/modules), **Data Structures** (exact structs/types),
**Transformations** (how data is modified).

### Section 4 — Cross-Layer Dependencies

How layers are coupled; identify brittle connections (esp. untyped boundary contracts
like template `data-*` attributes, WebSocket message shapes, or shared JSON schemas).

### Section 5 — Critical Constraints

Project-specific invariants this flow depends on. Cite the constraints file by ID where
applicable.

### Section 6 — Mutation Impact

When modifying [X], check: direct deps, indirect deps, serialization boundaries,
rendering layers. Define **silent failures** and **hard failures** explicitly.

### Section 7 — Common Pitfalls

Typical mistakes by developers or LLMs (e.g. funneling a high-precision value through
a float pipeline, editing one of a duplicated calc, renaming a load-bearing legacy field).

### Section 8 — Evidence

File paths, code references, snippets supporting claims.

### Section 9 — Compact Knowledge (LLM-Optimized)

Max 200–300 words, no repetition, high density. Structure: one-line Flow; Key
Architectural Patterns (2–4); Critical Constraints; Mutation Checklist.

### Section 10 — Export (paths are exact — write these)

```text
📄 <WIKI-ROOT>/code-analysis/<domain>/flow.full.md      ← Sections 1–8
📄 <WIKI-ROOT>/code-analysis/<domain>/flow.compact.md   ← Section 9
📄 <WIKI-ROOT>/code-analysis/<domain>/patterns.md       ← if reusable behavior found (create/extend)
📄 <WIKI-ROOT>/code-analysis/<domain>/impact.md         ← if non-trivial risk found (create/extend)
📄 <WIKI-ROOT>/code-analysis/<domain>/<subarea>.impact.md ← if a sub-area has its own blast radius
📄 <WIKI-ROOT>/index.md                                 ← MANDATORY: add/refresh entries for every
                                                          file created, extended, or merged
```

Domain naming: name after the **feature area** being modified, not an abstract layer
(`mempool/`, `checkout/`, `block-table/`). If a feature touches an existing domain,
extend that domain's files — never create a parallel file for an existing flow. If a
new domain is required, add its entries to `<WIKI-ROOT>/index.md` (no justification
needed).