source-command-audit-analyze-code-ia-practices

name	source-command-audit-analyze-code-ia-practices
description	Review the codebase against the best-practices rubric and propose INTELLIGENT refactors (not random splits).

source-command-audit-analyze-code-ia-practices

Use this skill when the user asks to run the migrated source command analyze-code-ia-practices.

Command Template

🧠 Analyze code — IA best practices

Audit the codebase (focus: $ARGUMENTS if given, else the whole repo) against the rubric and propose improvements with engineering judgment.

1. Read both rubric files + the constitution:
   • contextkit/best-practices.md — the rubric (Tier 1 system & architecture; Tier 2 module & function hygiene; the four-block Principle / Smells / Fix / Don't over-apply per rule).
   • contextkit/review-protocol.md — the protocol (severity vocabulary anchored on scanner sev 1..5; scope / spike relaxations; report shape; scanner-vs-agent contract).
   • AGENTS.md constitution (especially §1 line budget, §2 SRP, §3 layers).
   • contextkit/config.json → l5.lineBudget for the project's thresholds.
2. Run the deterministic scan:

   node contextkit/tools/scripts/tech-debt-scan.mjs --json
   

   The scanner emits findings on a 1..5 severity scale from four detectors: line-budget (sev 3/5), srp-and (sev 2 — JS And/Or/E, Python _and_/_or_), react-state-loop (sev 3 — React/JSX only, > 2 useState + ≥ 1 useEffect), todo-marker (sev 1 — TODO/FIXME/ HACK/XXX). Custom detectors auto-load from contextkit/detectors/*.mjs. That is the floor of the report, not the ceiling.
3. Apply judgment the regex can't — in tier order:
   • Tier 1 first (architecture, no scanner help): does the domain depend on infrastructure (S1)? Are module boundaries respected (S2)? Any import cycles or god modules (S3)? Where does state live, and does it live once (S4)?
   • Tier 2 next (hygiene): walk the scanner findings. For each file, decide the right fix per H1's preference list:
     • Oversized file → name the responsibilities to extract (a hook, a service, a sub-component, a mapper) and where each goes. Never propose "split into two random files because it's long."
     • Leaked business logic in a transport handler → move it to the service/use-case layer.
     • Complex component state (> 2 useState + ≥ 1 effect) → extract a custom hook.
     • Big renderX() → promote to a real component.
     • Genuinely cohesive long file (a flat DTO/constants/types file) → say "leave it, document the cohesion in a header comment" rather than force a split.
   • Honor each rule's "Don't over-apply" clause. Manufactured findings cost more trust than they save. Silence is a valid result.
4. Route adjacent concerns out, don't smuggle them in. Security, a11y, privacy, and dependency/supply-chain are owned by other agents/commands (see Adjacent concerns at the foot of best-practices.md). If you spot one during the pass, name it briefly and dispatch the relevant agent/command — don't expand this command's lane.
5. Output a ranked report grouped by file. Each finding:

   path:line — TIER/§ID — SEVERITY — what's wrong — proposed fix
   

   Sort by tier (1 → 2), then severity (BLOCKER → NIT), then blast radius. Top 5 first; the rest below.
6. Do not persist findings in this command. It is analysis and creates no tasks, workflows, or source edits. Offer to open a focused /dev-start "refactor <file> by responsibility" (or /ship) on the top item.

If best-practices aren't active yet, ask the user whether to adopt them (set practices.active = true via /context-config and fill the AGENTS.md constitution).