# Cli Audit Xray

> >

- **Type:** Skill
- **Install:** `agentstack add skill-destynova2-cli-code-skills-cli-audit-xray`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Destynova2](https://agentstack.voostack.com/s/destynova2)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Destynova2](https://github.com/Destynova2)
- **Source:** https://github.com/Destynova2/cli-code-skills/tree/main/cli-audit-xray

## Install

```sh
agentstack add skill-destynova2-cli-code-skills-cli-audit-xray
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> **Optimization:** This skill uses on-demand loading. Heavy content lives in `references/` and is loaded only when needed.

> **Language rule:** Skill instructions are written in English. When generating user-facing output (reports, files, documentation), detect the project's primary language (from README, comments, docs, commit messages) and produce the output in that language. If the project is bilingual, ask the user which language to use before proceeding.

# Audit X-Ray — Semantic Optimization Scanner

Reveal what the code is really doing before proposing optimizations. The output is not "make it faster"; it is a ranked set of falsifiable optimization candidates with locations, invariants, validation methods, and handoffs to the skills that can prove or implement the next step.

Core rule:

> First reveal structure. Then propose hypotheses. Then classify risk. Then validate.

## What This Skill Adds

`cli-audit-xray` sits between static code quality, topology, drift, and performance work:

- `cli-audit-code` finds quality smells; X-Ray finds hidden semantic cost in otherwise acceptable code.
- `cli-audit-tangle` finds graph shape; X-Ray adds dataflow, resource flow, and optimization meaning to hot or tangled paths.
- `cli-audit-drift` checks code against contracts; X-Ray extracts missing invariants that should become contracts.
- `cli-forge-perf` proves runtime gains; X-Ray produces candidates worth benchmarking.

## Input

`$ARGUMENTS` is the target to inspect:

- **Function or file**: build a focused Semantic Optimization Graph around that code.
- **Directory**: sample likely hot paths, entrypoints, adapters, pipelines, and large loops.
- **Trace/flamegraph/profile path**: use the dynamic evidence to focus static inspection.
- **Empty**: inspect `src/` or the primary source directory at a shallow level.

## Mitosis — Scale Analysis to Scope

Reference `../shared/tiering.md` for canonical S/M/L/XL semantics.

| Scope | Tier | Behavior |
|---|---|---|
| One function / one hot path | **S** | Full semantic map + up to 5 optimization cards |
| One file / small module | **M** | Dataflow + resource flow + ranked cards |
| Directory / service slice | **L** | Sample top 10-15 risky paths; use tangle/perf evidence if available |
| Monorepo / distributed system | **XL** | Do not deep-scan everything; produce map of candidate zones and handoffs |

Bias down when unsure. A noisy X-Ray report is worse than a narrow one with strong evidence.

## Workflow

### Step 0 — Load Shared Contracts

Before producing findings:

1. Read `../gotchas.md` if it exists.
2. Read `../shared/optimization-card.md` for the canonical card contract.
3. Read `../shared/triage.md` for tier/confidence semantics.
4. Read `../shared/done-gate.md` and `../shared/gate-ladder.md` when a candidate requires proof or benchmark.
5. If present, read `.claude/tangle-partition.json` to focus on god functions, cycles, and boundary functions.
6. If present, read `CONTRACTS.md` before proposing rewrites that depend on behavior or invariants.

### Step 1 — Build the Mental SOG

Use `references/semantic-optimization-graph.md` for node types and mapping rules.

Extract:

- operations and transformations;
- data objects and shapes;
- control flow, loops, retries, async waits;
- resource flow: allocations, copies, serialization, locks, I/O, network, CPU/GPU boundaries;
- constraints and invariants;
- observable side effects;
- security and trust boundaries.

### Step 2 — Lift Where Useful

Use `references/optimization-families.md` when looking for patterns.

Lift imperative regions into maps, filters, reductions, scans, joins, state machines, tensor operations, graph traversals, policy decisions, or equations. Do not force math when it adds no decision value.

### Step 3 — Discover Candidates

Look for:

- repeated computation;
- common subexpressions;
- loop-invariant work;
- map/filter/reduce fusion;
- needless materialization;
- clone/copy/allocation hot spots;
- serialization/deserialization churn;
- bad cache placement;
- network or database calls inside loops;
- lock scope around I/O;
- CPU/GPU or device/host roundtrips;
- misplaced validation, DLP, auth, or policy boundaries.

### Step 4 — Gate Every Candidate

For each candidate, answer:

- What must be true?
- What could break?
- Which invariant is missing?
- How can we validate it?
- Is this a proof problem, benchmark problem, test problem, or architecture problem?

Use `references/risk-rules.md` for floating point, side effects, concurrency, and security boundaries.

### Step 5 — Report and Emit Envelope

Produce a Markdown report and, when running under `cli-cycle` or when writing files is allowed, emit `.claude/cli-audit-xray.json` following `../shared/result-schema.md`.

## Output Format

```markdown
# Semantic X-Ray Audit — {project-or-scope}

**Target**: {file/directory/hot path} | **Language**: {detected} | **Date**: {date}
**Scope tier**: S/M/L/XL | **Candidate count**: N

## Executive Summary
- Hidden structure found:
- Highest-leverage candidate:
- Highest-risk assumption:
- Next proof step:

## Semantic Map
### Dataflow
### Control Flow
### Resource Flow
### Trust / Security Boundaries

## Hidden Invariants
| Invariant | Evidence | Missing? | Downstream use |

## Optimization Candidates
{optimization cards using ../shared/optimization-card.md}

## Handoffs
| Target skill | Scope | Reason |

## Validation Plan
Map candidates to unit tests, property tests, benchmarks, trace comparisons, or contracts.
```

## Dynamic Handoffs

| Condition detected | Recommend | Why |
|---|---|---|
| Candidate requires runtime measurement, profile, or A/B proof | `/cli-forge-perf` | Use native benchmark protocol and significance gate |
| Candidate depends on an implicit behavior invariant | `/cli-audit-drift` | Promote the invariant into CONTRACTS.md or verify existing contract |
| Candidate sits in a god function, cycle, or unclear boundary | `/cli-audit-tangle` | Restructure or isolate before optimizing |
| Candidate needs new property/unit/negative tests | `/cli-audit-test` | Validate equivalence and prevent regressions |
| Semantic graph is useful to humans (> 12 nodes or cross-boundary flow) | `/cli-forge-schema` | Render Mermaid from the semantic map |
| Candidate touches auth, DLP, audit logs, retry, backpressure, or failover | `/cli-forge-resilience` | Treat it as operational risk, not only optimization |
| Candidate needs a CI perf gate or reproducible baseline | `/cli-forge-pipeline` | Make the validation repeatable in CI |

**Rule:** Recommend, don't auto-execute. Phrase as: "Consider running `/cli-forge-perf` — candidate X needs a reproducible A/B benchmark."

When running under `cli-cycle`, audit targets that usually run earlier (`cli-audit-tangle`, `cli-audit-drift`, `cli-audit-test`) are report-only recommendations if they already ran. Do not emit backward automatic handoffs that create a cycle; use their existing outputs when available.

## Rules

1. **No optimization claim without preconditions.** Say "valid if..." instead of "correct."
2. **No runtime gain claim without measurement.** If hardware, compiler, backend, cache, shape, distribution, or workload matters, mark it benchmarkable.
3. **Security before speed.** Do not move, remove, cache, or deduplicate auth/DLP/policy/audit behavior unless the trust boundary is preserved.
4. **Floating-point is not algebra over reals.** Mention NaN, infinity, rounding, overflow, underflow, tolerance, and order effects.
5. **Side effects are semantics.** Logging, metrics, mutation, global state, time, randomness, I/O, exceptions, cancellation, and locks can invalidate rewrites.
6. **Concrete locations only.** Every card should have `file:line` evidence when source is available.
7. **Do not fix by default.** This skill reports candidates and patch plans. Use explicit user direction before editing code.

## Integration with other cli-* skills

| Skill | Relationship |
|---|---|
| `cli-forge-perf` | X-Ray proposes benchmarkable candidates; perf proves or rejects them |
| `cli-audit-code` | Code quality can flag local smells that X-Ray turns into semantic-cost candidates |
| `cli-audit-tangle` | Tangle supplies topology and boundary functions; X-Ray supplies data/resource meaning |
| `cli-audit-drift` | Drift supplies contracts; X-Ray supplies missing invariants and rewrite preconditions |
| `cli-audit-test` | X-Ray identifies equivalence/property tests required by optimizations |
| `cli-forge-schema` | Renders semantic maps and resource-flow diagrams |
| `cli-forge-pipeline` | Turns recurring validation into CI gates |
| `cli-cycle` | Can run X-Ray as an adaptive Wave 2/3 audit and aggregate its JSON envelope |

## What This Skill Does NOT Do

- **Does not replace profilers.** It finds hypotheses; perf proves dynamic cost.
- **Does not replace topology analysis.** Use `cli-audit-tangle` for call graph partitioning.
- **Does not replace contracts.** Use `cli-audit-drift` to check intention vs implementation.
- **Does not auto-rewrite.** It can propose patch plans, but changes require explicit user direction.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Destynova2](https://github.com/Destynova2)
- **Source:** [Destynova2/cli-code-skills](https://github.com/Destynova2/cli-code-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-destynova2-cli-code-skills-cli-audit-xray
- Seller: https://agentstack.voostack.com/s/destynova2
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.