/arn-code-assess

name: arn-code-assess
description: >-
  This skill should be used when the user says "arness code assess", "arn-code-assess",
  "tech debt audit", "assess the project",
  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
argument-hint: "[scope]"

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 Agent tool, passing the model from `.arness/agent-models/code.md` as the `model` parameter (see `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/ensure-config.md` "Dispatch convention" for fallback). Context:

• The architect assessment prompt template from the protocol
• Codebase context: full content of `code-patterns.md`, `testing-patterns.md`, `architecture.md`
• Scope: the scope from G1

**If `has_ui_patterns` is true**, also invoke the `arn-code-ux-specialist` agent via t