/arn-code-assess

name: arn-code-assess
description: >-
  This skill should be used when the user says "arness code assess", "arn-code-assess",
  "assess codebase",
  "technical review", "codebase assessment", "find improvements", "what should I improve",
  "tech debt review", "tech debt audit", "pattern compliance check", "codebase health check",
  "assess the project", "improvement plan", "review my codebase", "what needs fixing",
  "code quality check", "audit my code", "run an assessment",
  or wants a comprehensive technical assessment of the codebase against stored patterns
  followed by prioritized improvement execution through the full Arness pipeline.
version: 1.0.0

Arness Assess

Run a comprehensive technical assessment of the codebase against stored patterns, let the user prioritize findings, then orchestrate the full Arness pipeline (spec → plan → execute → test → ship) for multiple improvements in a single session.

This skill is a **sequencer and decision-gate handler**, like arn-planning. It MUST NOT duplicate sub-skill or agent logic. All pipeline work is done by the invoked skills and agents. This skill handles: scope selection, assessment orchestration, finding prioritization, multi-spec pipeline management, and progress display.

Prerequisites

Check for a `## Arness` section in the project's CLAUDE.md. If missing, inform the user: "Arness is not configured for this project yet. Run `/arn-assessing` to get started — it will set everything up automatically." Do not proceed without it.

Additionally, verify that pattern files exist at the configured code-patterns path. At minimum, these must exist:

• `code-patterns.md`
• `testing-patterns.md`
• `architecture.md`

If any required pattern file is missing, inform the user: "Pattern documentation is incomplete. Run `/arn-assessing` which will generate pattern docs on first use."

Decision Gates

The skill pauses at exactly 7 gates. Steps marked (auto) flow without stopping.

| Gate | When | Question | Options | |------|------|----------|---------| | G1 | Entry | "What would you like to assess?" | Entire codebase / Specific area | | G2 | After assessment | "Ready to prioritize?" | Prioritize / Investigate further | | G3 | After prioritization | "How should improvements be organized?" | Bundle all / Separate specs / Arness suggests groupings | | G4 | After all plans generated | "Plans ready. Proceed?" | Approve all / Revise specific plan / Remove a spec | | G5 | Before each subsequent spec execution | "Conflict detected" (conditional) | Re-plan / Proceed / Skip | | G6 | After test results | "Tests [pass/fail]. Proceed?" | Ship / Fix and re-test / Abort | | G7 | Final | "Ship it?" | Commit, push & PR / Just commit / Not yet |

Pipeline Overview

Arness Assess: scope → assess → prioritize → spec(s) → plan all → save all → [taskify+execute]×N → test → ship

Workflow

Step 0: Initialize

1. Read the project's CLAUDE.md and extract the `## Arness` section. 2. Extract configuration fields:

• **Plans directory** — where plans and project folders live
• **Specs directory** — where specs and assessment reports are stored
• **Code patterns** — path to pattern documentation directory
• **Docs directory** — for documentation generation
• **Git** — whether git is configured
• **GitHub/Platform** — for shipping

3. Load pattern files from the configured code-patterns path:

• `code-patterns.md` (required)
• `testing-patterns.md` (required)
• `architecture.md` (required)
• `ui-patterns.md` (optional — sets `has_ui_patterns = true`)
• `security-patterns.md` (optional — sets `has_security_patterns = true`)

Step 1: Detect Assessment State (Resumability)

Check for existing assessment artifacts:

| Artifact | Detected State | |----------|---------------| | `ASSESSMENT_*.md` in specs-dir + executed plans with reports | Near-complete — resume at test gate | | `ASSESSMENT_*.md` in specs-dir + project folders with TASKS.md | Mid-execution — resume at taskify+execute | | `ASSESSMENT_*.md` in specs-dir + PLAN_PREVIEW files | Plans ready — resume at G4 | | `ASSESSMENT_*.md` in specs-dir + FEATURE specs matching assessment IDs | Specs written — resume at plan all | | `ASSESSMENT_*.md` in specs-dir only | Assessment done — resume at G2 (prioritize) | | None | Fresh start — begin at G1 |

If artifacts detected, ask: "It looks like you have an in-progress assessment. Resume from [stage], or start fresh?"

---

Step 2: Gate G1 — Scope Selection

Show progress:

Arness Assess: SCOPE → assess → prioritize → spec(s) → plan → save → execute → test → ship             ^^^^^

Even if the user triggered the skill with arguments (e.g., "assess the auth module"), confirm scope with `AskUserQuestion`:

**"What would you like to assess?"**

Options: 1. **Assess entire codebase** — Full review against all stored patterns 2. **Assess specific area** — Review a particular module, directory, or concern

If **specific area**: ask the user to describe the area (module name, directory path, or concern like "authentication" or "API layer").

Store the scope for agent invocations. Derive a scope name for the assessment file:

• Entire codebase → `full-codebase`
• Specific area → kebab-case of the area (e.g., `auth-module`, `api-layer`)

---

Step 3: Assessment

Show progress:

Arness Assess: scope → ASSESS → prioritize → spec(s) → plan → save → execute → test → ship                      ^^^^^^

Inform: "Running assessment agents against stored patterns..."

Read the assessment protocol:

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-assess/references/assessment-protocol.md

**Agent invocations — launch all applicable agents in parallel:**

**Always invoke the `arn-code-architect` agent** via the Task tool, passing the model from `.arness/agent-models/code.md` as the `model` parameter (see `plugins/arn-code/skills/arn-code-ensure-config/references/ensure-config.md` "Dispatch convention" for fallback).