/mariana — Mariana Trench Audit

Full-depth multi-dimensional audit of a codebase or product. Designed to surface every defensible finding across security, accessibility, UX, performance, SEO, database, architecture, legal compliance, ops, and documentation.

Powered by graphify. Without a knowledge graph the skill runs at half potency. The first thing it checks is graph presence and freshness.

Empirically validated. This skill is the codified outcome of an audit run in May 2026 against aglaya-kanban-desk (Express + Supabase + React stack) that surfaced 1 XSS (CVSS 8.0) and 1 backup-strategy CRITICAL in the first session, both mitigated the same day with verified end-to-end fixes.

Usage

/mariana                       # audit current directory, ask mode interactively
/mariana <path>                # audit specific path
/mariana --mode report         # report-only, no fixes (default if unspecified)
/mariana --mode mitigate       # mitigate every CRITICAL IMMEDIATE as it appears (XSS, backup, etc.)
/mariana --mode case-by-case   # pause and ask per-finding whether to mitigate
/mariana --resume              # resume from last incomplete fase (reads audits/YYYY-MM-DD-mariana/state.json)
/mariana --no-cross-canon      # skip global graph cross-canon checks
/mariana --dimensions A,B,D    # run only specific fases (comma-separated)

What you MUST do when invoked

Step 0 — Mode + scope selection

If --mode not passed, ask user:

Select audit mode:

1. report — audit only, no fixes. Output: REPORT.md + findings.json. Remediation in separate sessions.
2. mitigate — audit + automatically mitigate any CRITICAL IMMEDIATE finding using a validated playbook (XSS upload, backup strategy, etc.). Only CRITICAL — HIGH/MEDIUM/LOW stay in the report.
3. case-by-case — audit + for every CRITICAL/HIGH finding, pause and ask mitigate / leave in report / skip.

If <path> not given, use . (current directory).

Step 1 — Prerequisite check + cooldown gate

Mariana audit relies on the knowledge graph and consumes meaningful tokens. Two gates run before any work begins.

1a — Cooldown gate (avoid wasteful re-runs)

Run the cooldown script:

SKILL_DIR="$HOME/.claude/skills/mariana-audit"
VERDICT="$(bash "$SKILL_DIR/bootstrap/check-cooldown.sh" 2>/dev/null || echo FRESH)"

The verdict is one of:

• FRESH — no previous audit; proceed.
• RUN — previous audit is stale (>30 days) or significant activity since; proceed.
• PARTIAL — moderate activity; recommend the user pass --dimensions <A,B,...> to audit only what changed. Show the cooldown explanation and ask if they want to continue full or switch to partial.
• SKIP — very recent audit + negligible activity. STOP and show the user when the next audit is recommended. Ask if they want to override with --force.

If the user invoked /mariana --force, the cooldown is bypassed. Show the cooldown summary anyway for context.

The cooldown reads from docs/audits/*-mariana/ directories. Without previous audits, it always returns FRESH.

1b — Tooling prerequisites

Run the master installer (idempotent — safe even if everything is already in place):

SKILL_DIR="$HOME/.claude/skills/mariana-audit"
bash "$SKILL_DIR/bootstrap/install.sh"

This script:

1. Installs graphify CLI if missing (tries uv → pipx → pip3 --user).
2. Verifies Claude Code CLI is authenticated for headless extraction (claude -p).
3. Onboards the repo to graphify if no local graph exists (extracts + publishes to global).
4. Installs graphify's own git hooks (post-commit + post-checkout).
5. Installs the doc-sync companion hook (vendored from the skill) so every commit auto-republishes the graph to global.

If any step fails, the script reports what's missing and exits with non-zero. The skill should then surface the specific error and refuse to continue.

Bypass envs (use sparingly):

• SKIP_INSTALL=1 — no-op the whole installer.
• SKIP_ONBOARD=1 — skip onboarding (use existing graph).
• SKIP_HOOKS=1 — skip hook installation.
• MARIANA_TAG=<tag> — override repo tag (default: directory name).
• MARIANA_CONTINUE_WITHOUT_CLAUDE=1 — proceed even if Claude Code CLI is unauthenticated (audit will run with reduced power).

If the user accepts a degraded setup (stale graph, missing global publication, etc.), note the warning in the final REPORT.md.

Step 2 — Phase 0: setup and scope matrix

Create output directory docs/audits/YYYY-MM-DD-mariana/ (use today's UTC date).

Run scope detection. Map the project to detect stack archetype:

1. Run graphify query "stack architecture entry point" against the local graph.
2. Inspect for archetype indicators:
   • package.json → JS/TS frontend or Node backend
   • pyproject.toml / requirements.txt → Python
   • Cargo.toml → Rust
   • go.mod → Go
   • index.html at root + no backend → static site (vitrina)
   • astro.config.* → Astro static or hybrid
   • next.config.* → Next.js
   • vite.config.* + React/Vue → SPA
   • Dockerfile + *.py + FastAPI imports → Python backend
   • *.sql migrations + Supabase imports → Supabase Postgres
   • .github/workflows/ → CI present
   • Sentry/OpenTelemetry/pino imports → observability layer
   • helmet/express-rate-limit → security middleware
   • multer → file upload (XSS-via-upload vector — flag for Phase B priority)

Build the scope matrix and report to user:

Stack detected: <archetype>
Dimensions in scope (mark N/A with reason):

#  Dim                       Applicable   Reason
1  Security                 YES / N/A   <reason>
2  Accessibility WCAG 2.1    YES / N/A   <reason>
3  Usability                YES / N/A   <reason>
4  Performance               YES / PARTIAL <reason — e.g., Core Web Vitals NOT VERIFIABLE without deploy>
5  Databases            YES / N/A   <reason>
6  Technical SEO               YES / N/A   <reason — auth-walled → mark partial: solo OG share tags>
7  Architecture + technical debt      YES
8  Legal compliance        YES / N/A   <reason — internal-only tool no third-party data>
9  Cookies + consent         YES / N/A   <reason>
10 Data retention + DPA      YES / N/A   <reason>
11 DevOps / CI               YES
12 Deployment + Observ.       YES / PARTIAL
13 Docs + maintainability     YES

Archetype-specific defaults:

• Static vitrina (HTML/Astro static, no backend): A pleno; B mínimo (no auth/DB); C cookies/privacy only if analytics; D docs only.
• SaaS with backend + DB: A→E full.
• CLI / library: B (deps, secrets); D (docs, tests, distribution). A and C usually N/A.
• Public API without UI: B + C full; A only perf/observability; D full.
• Internal-only tool with auth-walled UI: A full; B full; C reduced (no public privacy obligation, still internal compliance); D full.

Ask user OK Phase 0 (or --auto-ok if non-interactive). Wait for confirmation.

Step 3 — Phase A: Product surface

Dimensions: Accessibility (WCAG 2.1 AA), Usability, Performance, SEO.

Use graphify first, then read code raw only when graph doesn't surface the answer.

Accessibility (WCAG 2.1)

Required checks. Cite the WCAG criterion in each finding.