/assessment

name: assessment
description: "Assessment: read-only inspection, codebase overview, value analysis, health checks, ADR consultation, decision analysis, multi-perspective critique."
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
  - Skill
  - Agent
routing:
  not_for: "code review with findings (use review), building or fixing (use workflow)"
  triggers:
    - "inspect without changing"
    - "read-only"
    - "audit current state"
    - "onboard to codebase"
    - "codebase structure"
    - "give me an overview"
    - "summarize this repo"
    - "repo value analysis"
    - "what can we learn from"
    - "service status"
    - "check health"
    - "is service running"
    - "validate endpoints"
    - "consult on ADR"
    - "architecture consultation"
    - "adr consultation"
    - "help me decide"
    - "decision matrix"
    - "pros and cons"
    - "trade-offs"
    - "critique these ideas"
    - "devil's advocate"
    - "stress test proposals"
    - "roast this"
    - "poke holes in this"
  category: analysis
  pairs_with:
    - review
    - workflow
    - security

Assessment Skill

Seven modes for read-only analysis and decision support. Match the request to a mode, then follow that mode's phases.

Mode Selection

| Request pattern | Mode | |---|---| | Inspect, browse, explore without changing | [Read-Only Inspection](#read-only-inspection) | | Onboard, overview, summarize repo, codebase structure | [Codebase Overview](#codebase-overview) | | Repo value analysis, compare repos, what can we learn | [Repo Value Analysis](#repo-value-analysis) | | Service status, health check, uptime, validate endpoints | [Service Health Check](#service-health-check) | | Consult on ADR, challenge design, architecture consultation | [ADR Consultation](#adr-consultation) | | Help me decide, decision matrix, pros/cons, trade-offs | [Decision Scoring](#decision-scoring) | | Critique ideas, devil's advocate, stress test, roast | [Multi-Persona Critique](#multi-persona-critique) |

---

Read-Only Inspection

Safe exploration without modifying files or system state.

Phase 1: SCOPE

Parse the request. Determine target scope (file, directory, service, system-wide). Clarify before proceeding if scope could match dozens of results.

Phase 2: GATHER

Use read-only tools only.

**Allowed**: `ls`, `find`, `wc`, `du`, `df`, `file`, `stat`, `ps`, `top -bn1`, `uptime`, `free`, `pgrep`, `git status/log/diff/show/branch`, `sqlite3 "SELECT ..."`, `curl -s` (GET only), `date`, `env`.

**Forbidden**: `mkdir`, `rm`, `mv`, `cp`, `touch`, `chmod`, `chown`, `git add/commit/push`, file writes, `INSERT/UPDATE/DELETE/DROP`, `npm/pip/apt install`, `kill`, `systemctl restart`.

Phase 3: REPORT

Lead with the answer. Show supporting evidence. List files examined. All claims must cite evidence.

---

Codebase Overview

4-phase exploration producing an evidence-backed onboarding report. Read-only.

Read any `.claude/CLAUDE.md` or `CLAUDE.md` in the repo root first. Skip sensitive files (`.env`, `*.pem`, `*.key`, credentials) silently.

Phase 1: DETECT

Examine root directory. Identify project type from config files (`package.json`, `go.mod`, `pyproject.toml`, `pom.xml`, `Cargo.toml`). Document: language, framework, build system, dependencies. Load `references/codebase-overview/exploration-strategies.md` for language-specific discovery commands.

**Gate**: Project type identified. Tech stack documented.

Phase 2: EXPLORE

Discover entry points, core modules, data models, API surfaces, configuration, tests. Limit 20 files per category. Map directory structure (exclude `node_modules/`, `venv/`, `vendor/`, `dist/`, `build/`, `__pycache__/`).

**Gate**: Entry points, core modules, data layer, API surface, config, tests documented.

Phase 3: MAP

Identify design patterns with file evidence. Map 5-10 key abstractions. Trace a typical request through the full stack. Analyze last 10 commits. All paths absolute. All claims cite source files.

**Gate**: Patterns identified, abstractions mapped, data flow documented.

Phase 4: SUMMARIZE

Generate report using `references/codebase-overview/report-template.md`. Include "Where to Add New Code" section. Run post-exploration secret scan.

For deep-dive mode ("full picture"), launch 4 parallel domain agents via Task. See `references/codebase-overview/examples-and-errors.md` for dispatch template.

**Scripts**: `scripts/cartographer.py` (quick), `scripts/cartographer_omni.py` (100-metric), `scripts/cartographer_ultimate.py` (focused performance).

---

Repo Value Analysis

6-phase pipeline analyzing external repositories for adoptable ideas.

Phase 1: CLONE

Parse input (GitHub URL, local path, `org/repo`). `git clone --depth 1`. Categorize files into zones (skills, agents, hooks, docs, tests, config, code, other). Cap zones at ~100 files.

Phase 2: DEEP-READ (parallel)

Dispatch 1 Agent per zone (up to 8). Each reads EVERY file and produces: component inventory, key techniques, notable patterns, gaps. Output to `/tmp/[REPO]-zone-[zone].md`.

**Gate**: 75%+ agents returned.

Phase 3: INVENTORY (parallel with Phase 2)

Dispatch 1 Agent to catalog vexjoy-agent repo: agents, skills, hooks, scripts with counts. Output to `/tmp/self-inventory.md`.

Phase 4: SYNTHESIZE

Read all zone findings and inventory. Build comparison table. Rate gaps: HIGH/MEDIUM/LOW. Save draft to `research-[REPO]-comparison.md`.

Phase 5: AUDIT (parallel)

For each HIGH/MEDIUM recommendation, dispatch 1 audit Agent to verify: ALREADY EXISTS, PARTIAL, or MISSING. Skip with `--quick`.

Phase 6: REPORT

Adjust recommendations from audit. Write final report: executive summary, comparison table, already-covered, recommendations, verdict, next steps. Clean `/tmp/` files. Load `references/repo-value-analysis/phase7-implement-template.md` for implementation dispatch.

---

Service Health Check

Deterministic service m