# Assessment

> Audit an implementation's architecture for completeness, missing patterns, and planted defects before a take-home or interview submission.

- Skill: `gufranco/assessment` (Agent Skill)
- Install (CLI): `npx get-skill add gufranco/assessment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gufranco/assessment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: gufranco (https://skillmd.com/u/gufranco)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/gufranco/assessment

---


## Overview

Perform an architecture completeness audit on an implementation. Unlike `/review` which checks diffs for correctness, this skill reads the full implementation and identifies **what's missing**: architectural patterns, resilience strategies, security measures, API contracts, and design decisions that should be present but aren't.

Designed for self-assessment before submitting work, whether in an interview, a take-home, or before declaring a feature complete.

## Subcommand Routing

| Invocation | Action |
|-----------|--------|
| `/assessment` or `/assessment <path>` | Architecture completeness audit on the named files or the current branch (default) |
| `/assessment harness` | Audit `~/.claude/` itself against the twelve-category harness rubric (see Harness Audit section below) |
| `/assessment skills` | Audit the user's skill portfolio for unused, stale, overlapping, or under-documented skills (see Skills Audit section below) |

The default branch with no subcommand is the architecture audit. The two new subcommands target `~/.claude/` itself, not the current project.

## When to use

- After implementing a feature and before saying "I'm done."
- Interview self-check: catch missing architectural patterns before the interviewer does.
- Design validation: verify a solution covers all the patterns it should.
- Pre-production readiness: verify deployment, security, and operational patterns.
- Learning: understand which architecture concepts apply to a given problem.
- Annual review of `~/.claude/` itself, `harness` and `skills` subcommands.

## When NOT to use

- For reviewing a diff or PR. Use `/review` instead.
- For trivial changes that don't involve architecture decisions.

## Arguments

This skill accepts optional arguments after `/assessment`:

- No arguments: assess all changed files on the current branch compared to the base branch.
- A file or directory path: assess those specific files.
- `--scope <description>`: provide a description of what was implemented so the assessment can focus on relevant patterns.
- `--focus <area>`: narrow the assessment to a specific concern: `security`, `resilience`, `api`, `data`, `ops`, `quality`, `tenancy`, `infra`, `slop`, or `all` (default).
- `--rationale`: when fixing gaps, collect the reasoning behind each change into a `DECISIONS.md` at the repo root. Useful for interview take-homes where reviewers need to follow your decision-making. The reasoning goes in that file, never in a source comment. This is the default way to explain a change.
- `--comments`: same reasoning, written as inline comments above each change instead. Only for an external take-home whose reviewer expects annotated source. This deliberately violates [`../../standards/code-style.md`](../../standards/code-style.md) "Comments Policy", so it requires `COMMENT_BLOCKER_DISABLE=1` exported in the parent shell before the session starts. Without that export, [`../../hooks/comment-blocker.py`](../../hooks/comment-blocker.py) blocks every write and the flag cannot work.

## Steps

1. **Understand the requirements.** Before assessing the implementation, understand what was asked.
   - Scan the **entire project** for requirement and context documents, not just the root or [`docs/`](../../docs). Search all directories for files named README, INSTRUCTIONS, BRIEF, ASSIGNMENT, REQUIREMENTS, CHALLENGE, TASK, PROMPT, PROBLEM, SPEC, DESIGN, ARCHITECTURE, ADR, or similar, in any format: `.md`, `.txt`, `.pdf`, `.docx`, `.html`. Also check for hidden files like `.assignment`, `.brief`, or dotfiles that might contain instructions.
   - Read every document found. Extract: the problem statement, explicit requirements, evaluation criteria, constraints, time limits, and bonus/stretch goals if mentioned.
   - Ask the user: **"Do you have additional instructions from email, a job posting, or other external sources that I should consider? If this is for a specific company, what is the company name? Were any external projects, codebases, or articles used as reference during implementation?"** Wait for a response before proceeding. If the user provides text, screenshots, or URLs, incorporate that as additional requirements context. If external sources were consulted, record them for category 50, Clean Room verification in step 7.
   - **Company research.** If a company name is provided, search for their engineering blog, tech blog, GitHub organization, open source projects, tech talks, and **Glassdoor interview reviews**. Glassdoor is especially valuable: candidates often share the exact take-home problem, evaluation criteria, interview questions, and what the company looks for. Search for `"<company name>" interview software engineer site:glassdoor.com` and similar queries. Also understand what technologies they use, what patterns they value, and what their engineering culture looks like. A company that blogs about event sourcing will notice if you didn't use it. A company with strict TypeScript repos will judge a loosely-typed submission. Use this context to prioritize which patterns matter most for the assessment.
   - Record all requirements, but treat them as a **floor, not a ceiling**. The explicit requirements define the minimum. The assessment should go well beyond them, identifying patterns and improvements that would make the implementation stand out. In interview contexts, what separates a passing submission from an impressive one is the engineering depth that was not explicitly asked for.

2. **Gather the implementation.** Run these **in parallel**:
   - `git branch --show-current` to get the current branch.
   - Detect the base branch, using the same logic as `/review`.
   - `git fetch origin` to ensure remote is up to date.
   - If a path argument was given, use that. Otherwise, get the list of changed files: `git diff origin/<base>...HEAD --name-only`.
   - If `--scope` was provided, record the description for context.

3. **Read the full implementation.** Read every changed file in full, not just the diff. The goal is to understand the complete solution, not just what changed. Also read key surrounding files: imports, configs, schemas, middleware, route definitions, environment files.

4. **Discover applicable standards and rules.** Read `~/.claude/rules/index.yml`. Scan the project for technology signals: file extensions, framework markers, `package.json`, `go.mod`, `Cargo.toml`, `Gemfile`, `requirements.txt`, `pyproject.toml`, import statements, directory names, and config files such as `.graphqlrc`, `terraform/`, `k8s/`, `docker-compose.yml`, `.eslintrc`, `tsconfig.json`, `playwright.config.*`, `.proto` files, `i18n/` or `locales/` directories, `Dockerfile`, and [`.github/workflows/`](../../.github/workflows).

   Match signals against trigger keywords in the `on_demand` section of the index. Load **every** matched standard file. Also load **all** `always_loaded` rules.

   Record which standards and rules were loaded. These become additional audit criteria in step 8, beyond the 71-category checklist. A project using PostgreSQL loads [`standards/database.md`](../../standards/database.md). A project with GraphQL loads [`standards/graphql-api-design.md`](../../standards/graphql-api-design.md). A project with Terraform loads [`standards/terraform-testing.md`](../../standards/terraform-testing.md). Every applicable standard is loaded, no exceptions.

   Additionally, load these references for use during fix and convergence phases:
   - [`rules/architecture-defaults.md`](../../rules/architecture-defaults.md): universal principles, six-question architecture gate, hard rules, domain layer contract, idempotency and deduplication specifics. Always-loaded baseline that drives the DDD/hexagonal/state-machine decisions in step 7
   - [`rules/pre-flight.md`](../../rules/pre-flight.md): verify interfaces before implementing fixes
   - [`rules/verification.md`](../../rules/verification.md): evidence-based verification for every claim, zero warnings
   - [`rules/writing-precision.md`](../../rules/writing-precision.md): quality gate for generated README and comments
   - [`rules/anti-slop.md`](../../rules/anti-slop.md) and [`standards/anti-slop.md`](../../standards/anti-slop.md): the slop tells step 5 scans for and the fix order step 10 uses
   - [`rules/git-workflow.md`](../../rules/git-workflow.md): commit format during fix phase
   - [`rules/security.md`](../../rules/security.md): security criteria beyond the checklist categories, OAuth 2.1, passkeys, NIST 800-63B, secrets management, supply chain
   - [`rules/code-style.md`](../../rules/code-style.md): completeness, immutability, error classification, type conventions, LLM trust boundary, TypeScript 5.x patterns
   - [`rules/testing.md`](../../rules/testing.md): mock policy, test structure with the three bare AAA markers as the only comments, faker, deterministic tests, coverage, contract testing, performance regression
   - [`rules/ai-guardrails.md`](../../rules/ai-guardrails.md): when code processes LLM output, validate trust boundaries
   - [`rules/smart-questions.md`](../../rules/smart-questions.md): question format, status reports, FIXED/RESOLVED/DONE loop closure
   - [`rules/surgical-edits.md`](../../rules/surgical-edits.md): each diff line must trace to the request
   - [`rules/design-philosophy.md`](../../rules/design-philosophy.md): Ousterhout complexity heuristics for refactor fixes, deep modules, design it twice, red flags catalog
   - [`rules/found-fix.md`](../../rules/found-fix.md): pre-existing findings surfaced by the audit are in scope for the current fix pass. Banned rationalizations and the enforcement boundary
   - [`rules/no-ai-process-leak.md`](../../rules/no-ai-process-leak.md): commit messages, PR descriptions, and code comments produced during the fix phase must read as if a human wrote them
   - [`standards/documentation.md`](../../standards/documentation.md): preservation rules when updating project docs
   - [`standards/debugging.md`](../../standards/debugging.md): 4-phase process when diagnosing planted defects in step 6
   - [`standards/performance.md`](../../standards/performance.md): Core Web Vitals budgets, API latency targets, bundle size limits
   - [`standards/privacy.md`](../../standards/privacy.md): data minimization, retention, erasure, consent, pseudonymization
   - [`standards/context-management.md`](../../standards/context-management.md): compact discipline and re-read cadence during long audits
   - [`standards/cost-awareness.md`](../../standards/cost-awareness.md): cloud and runtime cost trade-offs
   - [`standards/code-review.md`](../../standards/code-review.md): includes the "As Reviewee" section. When the assessment surfaces gaps that will be addressed via a PR, this is the reference for how the author should handle reviewer feedback
   - [`rules/lang/typescript-types.md`](../../rules/lang/typescript-types.md), `typescript-immutability.md`, `typescript-strict.md`: load when TypeScript is detected
   - [`rules/lang/orm-migrations.md`](../../rules/lang/orm-migrations.md): consolidated ORM migrations rule covering Prisma, TypeORM, Drizzle, Sequelize, and MikroORM. Load when any ORM is detected

   Before coding any fix that calls a library API, check [`standards/llm-docs.md`](../../standards/llm-docs.md) for the library's documentation URL. Fetch the docs and verify the API exists. Never guess API signatures.

5. **Verify the project works.** Before analyzing architecture, confirm the project actually builds and passes its own tests. A project that doesn't compile is worse than any missing pattern. Run these **in parallel** where possible:

   - **Build**: detect the build system and run it, `pnpm build`, `make`, `go build`, `cargo build`, etc. Record success or failure with output.
   - **Lint**: run the project's linter, `pnpm lint`, `eslint`, `golangci-lint`, `ruff`, etc. Record warnings and errors.
   - **Typecheck**: if applicable, run the type checker, `pnpm typecheck`, `tsc --noEmit`, `mypy`, etc. Record any type errors.
   - **Tests**: run the test suite with coverage, `pnpm test -- --coverage`, `pytest --cov`, `go test -cover`, etc. Record pass/fail count and coverage percentage.
   - **Runtime and language version**: check the language and runtime version the project uses. **Always upgrade to the latest stable LTS version.** If the project runs on a managed platform with version constraints, AWS Lambda, Google Cloud Functions, Azure Functions, Vercel, Heroku, etc., use the latest stable version available on that platform. Check the platform's documentation to confirm which versions are supported. Update **all** version references: config files, CI pipelines, Dockerfiles, IaC templates like `Runtime` in SAM, CloudFormation, or Terraform, and README. Verify the project builds and passes tests after the upgrade.

     **Runtime version pinning is mandatory.** The project must use a version manager config file so every developer and CI environment uses the same version. Prefer `mise`, single tool for every ecosystem, reads legacy files for compatibility. Add the appropriate file if missing:

     | Ecosystem | Recommended | Also accepted | Config file |
     |:----------|:------------|:--------------|:------------|
     | Multi-language (preferred default) | mise | asdf | `.mise.toml` (mise canonical), `.tool-versions` (asdf-compatible, also read by mise) |
     | Node.js | mise | fnm, volta, nvm | `.mise.toml`, `.tool-versions`, `.node-version`, `.nvmrc` |
     | Python | mise | pyenv | `.mise.toml`, `.tool-versions`, `.python-version` |
     | Ruby | mise | rbenv, rvm | `.mise.toml`, `.tool-versions`, `.ruby-version` |
     | Go | mise | goenv | `go.mod` `go` directive, `.mise.toml`, `.tool-versions` |
     | Rust | rustup | mise (with rust plugin) | `rust-toolchain.toml` |
     | Java | mise | sdkman | `.mise.toml`, `.tool-versions`, `.sdkmanrc`, `.java-version` |
     | Terraform | mise | tfenv | `.mise.toml`, `.tool-versions`, `.terraform-version` |

     Also set `engines` in `package.json`, Node.js, `requires-python` in `pyproject.toml`, Python, or the equivalent for other ecosystems. This enforces the version constraint in the package manager, not just the version manager.

     An outdated runtime is a MEDIUM finding. A runtime past end-of-life is HIGH. Missing version manager config is MEDIUM.
   - **Dependency audit and update**: run the package manager's audit command, `pnpm audit`, `uv run pip-audit`, `cargo audit`, etc. Record any known vulnerabilities by severity. Then check for outdated dependencies, `pnpm outdated`, `uv pip list --outdated`, etc. **Assume dependency versions may be intentionally outdated, vulnerable, or incompatible with the current platform** (e.g., packages that fail on Apple Silicon, deprecated Node.js versions, libraries with known CVEs). Always update all dependencies to their latest stable versions. Run `pnpm update --latest`, or equivalent and verify the project still builds and passes tests after the update. If a specific update breaks something, pin that dependency at the last working version and document why.
   - **AI slop scan**: run `python3 ~/.claude/tools/slop-scan.py <repo> --commits origin/<base>..HEAD`. It reuses the detectors of [`../../hooks/ai-slop-blocker.py`](../../hooks/ai-slop-blocker.py) over every Markdown file, skipping dependency and build directories, and over each commit message in the range. Exit 0 is clean, 1 lists findings, 2 is a scan error and counts as a failed check. Add `--json` to parse the rows. Record each finding by code.
   - **Output verification**: if the requirements include example inputs, expected outputs, or acceptance criteria, actually run the code with those inputs and verify the results match. Reading the code and believing it works is not proof.

   Any failures in this step are findings. A failing build or test is CRITICAL. Lint errors are MEDIUM. Dependency vulnerabilities are HIGH if exploitable, MEDIUM otherwise. Outdated dependencies are MEDIUM. Test coverage below 100% on any file is HIGH, and an exclusion directive or omit entry for hand-written code is HIGH.

   Record all results for inclusion in the assessment output.

6. **Hunt for planted defects.** Some projects, especially interview take-homes and coding challenges, contain **intentional bugs, anti-patterns, or subtle correctness issues** designed to test whether the candidate can spot and fix them. Read the code with suspicion. For each file, look for: logic bugs, data bugs, validation gaps, concurrency bugs, security flaws, anti-patterns, configuration issues, dependency traps, test gaps, mock abuse, and structural violations. The specific criteria for each category are defined in [`../../checklists/checklist.md`](../../checklists/checklist.md) categories 1-9, 17, 18-49, and 50. Use the checklist as the hunting guide, but read with the assumption that defects may be intentional. Pay special attention to tests that mock internal infrastructure like databases, Redis, or queues instead of using real connections: this is a common defect that makes tests pass while the actual code is broken.

   If any defect is found, classify it with the same severity/effort scale used for missing patterns. Planted bugs that affect correctness or security are always CRITICAL.

7. **Classify the implementation.** Determine what type of system this is, informed by both the code and the requirements gathered in step 1.

   **Architecture gate, run first.** Before walking the trait table, answer the six questions from [`../../rules/architecture-defaults.md`](../../rules/architecture-defaults.md) Architecture Gate. Each "yes" forces the matching standard to load regardless of `--focus`:

   | Question | If yes, force-load |
   |----------|-------------------|
   | Does this involve business rules, state transitions, or invariants beyond CRUD? | [`../../standards/ddd-tactical-patterns.md`](../../standards/ddd-tactical-patterns.md) |
   | Are there two or more infrastructure dependencies (DB + queue, DB + external API)? | [`../../standards/hexagonal-architecture.md`](../../standards/hexagonal-architecture.md) |
   | Is the operation mutating shared state, persisting data, or producing side effects? | [`../../standards/resilience.md`](../../standards/resilience.md) for idempotency and dedup |
   | Does the operation cross trust boundaries: HTTP, queue, external API, LLM output? | [`../../standards/code-style.md`](../../standards/code-style.md) Validation section |
   | Are there multiple states or transitions for a domain object? | [`../../standards/state-machines.md`](../../standards/state-machines.md) |
   | Can two actors run it at once? Defaults to yes with more than one entry point, a user who can trigger it twice, or a network retry | [`../../standards/concurrency.md`](../../standards/concurrency.md) |

   If two or more questions answer yes, this is non-trivial work. Findings for missing DDD aggregates, missing port/adapter separation, missing idempotency keys, missing dedup windows, boolean-blind state representations, or an unguarded race between two actors are at least HIGH severity.

   **Trait table.** Each trait maps to a set of applicable categories:

   | Trait | Signal | Categories to check |
   |:------|:-------|:-------------------|
   | Has a write path | API endpoints, event handlers, DB writes | 18, 19, 34, 39 |
   | Has a read path | Queries, API responses, dashboards | 21, 31, 34 |
   | Has external deps | HTTP calls, third-party APIs, DB connections | 20, 24, 35, 38, 42, 68 |
   | Has async processing | Queues, events, background jobs | 18, 27, 36, 57 |
   | Spans multiple services | Service-to-service calls, event bus | 22, 26, 28, 29, 41 |
   | Handles variable load | Public API, webhook receiver, batch processor | 23, 25, 40, 65 |
   | Stores data | Database reads/writes, file storage | 19, 30, 31, 39, 40, 63, 69 |
   | Has auth/user data | Login, signup, roles, PII | 33, 67 |
   | Handles payments or balances | Payment endpoints, balance operations, betting, e-commerce transactions | 33, 34, 19, 60, 67 |
   | Exposes an API | REST/GraphQL endpoints | 34 |
   | Runs in production | Deployed service, not a script or CLI | 32, 35, 37, 38, 42, 64 |
   | Has testable logic | Business rules, domain logic, state machines | 41 |
   | Serves multiple tenants | SaaS, shared infrastructure, per-customer data | 43 |
   | Replaces existing system | Migration, rewrite, platform change | 44 |
   | Has infrastructure config | Terraform, CloudFormation, Pulumi, Dockerfiles, K8s manifests | 45, 47, 48 |
   | Uses cloud services | AWS/GCP/Azure resources, managed services | 45, 46, 49, 66 |
   | Processes LLM output | AI-generated content stored or acted on | 53 |
   | Has frontend with metrics | Web app with user-facing pages | 54, 62 |
   | Deploys to production | CI/CD pipeline, deployment config | 55 |
   | Handles dates across time zones | Scheduling, recurring events, multi-region timestamps | 59 |
   | Performs money or rate math | Currency conversion, financial multiplications, scientific computation | 60 |
   | Supports multiple locales | i18n strings, RTL layouts, plural rules, regional variants | 61 |
   | Handles PII or regulated data | GDPR, LGPD, HIPAA, financial, audit-trail requirements | 67 |
   | Depends on third-party services beyond standard libs | Vendor APIs, SaaS integrations, payment processors | 68 |
   | Uses an ORM with migrations | Prisma, TypeORM, Drizzle, Sequelize | 69 |
   | Has dependencies | package.json, go.mod, requirements.txt | 56 |
   | Uses events or queues | Message brokers, event handlers, pub/sub | 57 |

   If `--focus` was provided, only check categories in that area and force-load the corresponding standards. The standard paths below match the current `~/.claude/standards/` directory. Several names from earlier versions of this skill were consolidated or renamed: `cost-optimization.md` is now `cost-awareness.md`; `event-driven-architecture.md` was absorbed into `message-queues.md`; `multi-tenancy.md`, `feature-flags.md`, `mlops.md`, `data-pipelines.md`, `grpc-services.md`, and `serverless-edge.md` were dropped and their guidance lives inline in other standards or in the always-loaded rules.

   - `security`: categories 33, 34. Standards: `security.md`. Also read `~/.claude/skills/security-patterns.md` and check every applicable pattern against the implementation. Injection patterns covering raw query, second-order, ORM operator, and command. Auth patterns covering JWT weakness, session cookies, auth state, and OAuth code atomicity. Authorization patterns covering IDOR and mass assignment. Race conditions covering read-modify-write, find-then-update, transaction isolation, lock fail-open, lock TTL, missing idempotency, and retry without idempotency. Web security covering CORS, unvalidated redirect, GraphQL depth and batching. The financial-platform checklist applies if payments or balances are present
   - `resilience`: categories 20, 23, 24, 25, 35, 36, 38. Standards: `resilience.md`, `caching.md`, `distributed-systems.md`
   - `api`: categories 18, 34. Standards: `api-design.md`, `contract-testing.md` when downstream consumers exist
   - `data`: categories 19, 21, 22, 30, 31, 39, 69. Standards: `database.md`, `identifiers.md`, `postgresql.md` when PostgreSQL is detected, `redis.md` when Redis is detected. ORM-specific schema-migration rules in the consolidated [`rules/lang/orm-migrations.md`](../../rules/lang/orm-migrations.md), which covers Prisma, TypeORM, Drizzle, Sequelize, and MikroORM in one file
   - `ops`: categories 32, 36, 37, 40, 42, 44, 51. Standards: `observability.md`, `infrastructure.md`, `cost-awareness.md`, `sre-practices.md`
   - `quality`: categories 41, 50, 52. Standards: `algorithmic-complexity.md`, `state-machines.md`, `ddd-tactical-patterns.md`, `hexagonal-architecture.md`, `railway-oriented-programming.md` when functional error handling is in use
   - `infra`: categories 45, 46, 47, 48, 49. Standards: `infrastructure.md`, `twelve-factor.md`, `terraform-testing.md`, `multi-account-cli.md` when multiple cloud accounts are configured
   - `clean-room`: category 50. Standard: `clean-room.md`
   - `graphql`: category 34. Standard: `graphql-api-design.md`
   - `realtime`: categories 20, 24, 35. Standard: `websocket-realtime.md`
   - `queues`: categories 18, 27, 36, 57. Standard: `message-queues.md`. This entry now also covers what was previously labeled `events`, since `event-driven-architecture.md` was absorbed
   - `mobile`: categories 7, 33, 41. Standard: `mobile-development.md`
   - `i18n`: category 7, plus 59, time zones and 61, locale edge cases when applicable. Standards: `i18n-l10n.md`, `i18n-regional-variants.md`
   - `docs`: category 14. Standard: `documentation-generation.md`, `documentation.md`
   - `slop`: category 14 plus the AI slop item in step 8. Standards: `anti-slop.md`, `writing-precision.md`
   - `frontend`: categories 7, 52, 54, 62. Standards: `frontend.md`, `accessibility-testing.md`, `browser-testing.md`, `performance-budgets.md`
   - `auth`: category 33. Standard: `authentication.md`
   - `deploy`: categories 51, 55. Standards: `zero-downtime-deployments.md`, `infrastructure.md`
   - `supply-chain`: category 56. Standards: `container-security.md`, `secrets-management.md`, `licensing.md` for SBOM and SPDX
   - `observability`: categories 32, 37. Standards: `observability.md`, `opentelemetry.md`, `sre-practices.md`, `dashboard-design.md`
   - `privacy`: category 33. Standards: `privacy-engineering.md`, `privacy.md`
   - `llm`: category 53. Standards: `llm-docs.md` for library documentation, `mcp-security.md` when MCP is involved. Use [`rules/ai-guardrails.md`](../../rules/ai-guardrails.md) and the LLM Output Trust Boundary section of [`standards/code-style.md`](../../standards/code-style.md)
   - `monorepo`: categories 13, 15. Standard: `monorepo.md`
   - `typescript`: category 1. Standards: `typescript-5x.md` plus the per-area files [`rules/lang/typescript-types.md`](../../rules/lang/typescript-types.md), [`rules/lang/typescript-immutability.md`](../../rules/lang/typescript-immutability.md), [`rules/lang/typescript-strict.md`](../../rules/lang/typescript-strict.md)
   - `all` (default): all applicable categories and all matched standards from step 4

   **Superset detection.** If the codebase uses a language that has a widely adopted superset offering stronger type safety or tooling, ask the user whether they want to convert. This is especially valuable in interview contexts where using the superset demonstrates engineering rigor.

   | Language | Superset | Key benefit |
   |:---------|:---------|:------------|
   | JavaScript | TypeScript | Static typing, compile-time error detection, better IDE support |
   | CSS | SCSS/Sass | Variables, nesting, mixins, modularity |
   | JSON config | JSON Schema or Zod validation | Runtime validation, self-documenting contracts |

   Ask: **"The project uses [language]. Would you like me to convert it to [superset]? This adds type safety and is generally viewed favorably in assessments."** Only ask once per language detected. If the user declines, proceed without converting. If the user accepts, add the conversion as a task in the fix step, before other fixes. Do not ask about superset conversion when the requirements explicitly specify the base language.

   **Strictest configuration possible.** When converting to a superset or when any tool, linter, compiler, or framework supports strictness levels, always configure the **maximum strictness**. TypeScript gets `strict: true` with all additional strict flags enabled, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, etc. ESLint gets the strictest recommended config. tsconfig gets `noEmit`, `isolatedModules`, `verbatimModuleSyntax`. This applies to everything: compilers, linters, formatters, test runners, security scanners, CI checks. If there is a stricter option, enable it. No exceptions.

   **Package compatibility with superset.** When converting to a superset, review every dependency for type support. For each package, follow this decision tree:

   1. **Package ships types natively**, has its own type declarations bundled. No action needed. Most modern packages do this.
   2. **Community type definitions exist**, separate package maintained by the community. Install them as dev dependencies. Examples by ecosystem:
      - JS/TS: `@types/express`, `@types/node`, `@types/jest`, etc. from DefinitelyTyped.
      - Python: `types-requests`, `django-stubs`, `types-PyYAML`, `boto3-stubs`, etc.
      - Ruby/Sorbet: RBI files from `tapioca` gem or community sources.
   3. **A typed alternative exists** that replaces the original package entirely with better superset support. Prefer the alternative. Examples:
      - `request` → `got` or `node-fetch` such as typed, maintained, or lighter
      - `moment` → `date-fns` or `dayjs` such as typed, tree-shakeable, or immutable
      - `underscore` → `lodash-es`, typed, tree-shakeable or native methods
      - `callback-based APIs` → their promise-based or async equivalents
   4. **No types exist and no alternative exists**. Write a minimal type declaration file, `.d.ts`, stub file, etc. for the parts of the API actually used. Never leave untyped imports.

   This logic is language-agnostic. The principle is: every dependency must have full type support in the target superset. If it doesn't, either find types, find an alternative that has types, or write the types yourself.

8. **Audit against each applicable category and loaded standard.** For every category that applies based on step 7, evaluate the implementation against [`../../checklists/checklist.md`](../../checklists/checklist.md). The checklist groups break down as: categories 1-17 for code-level quality, categories 18-49 for architecture and infrastructure, category 50 for clean room verification, category 51 for deployment verification, category 52 for design quality, category 53 for LLM trust boundary, category 54 for performance budget, category 55 for zero-downtime deployment, category 56 for supply chain security, category 57 for event-driven architecture, category 58 for licensing compliance, category 59 for time zone and calendar correctness, category 60 for numerical precision, category 61 for internationalization edge cases, category 62 for browser and device diversity, category 63 for backups and recovery, category 64 for disaster recovery, category 65 for capacity planning, category 66 for multi-region, category 67 for compliance and audit trail, category 68 for vendor and third-party risk, category 69 for schema-migration sync, category 70 for question and communication quality, and category 71 for frontend compliance defaults. Cross-reference with the requirements gathered in step 1. Include any defects found in step 6 and verification failures from step 5 as findings under the most relevant category.

   **Standard-based audit.** For every standard loaded in step 4, check whether the project follows the patterns described in that standard. Each standard contains specific, actionable rules. A project that uses a database but ignores [`standards/database.md`](../../standards/database.md) connection pooling guidance is a finding. A REST API that ignores [`standards/api-design.md`](../../standards/api-design.md) pagination conventions is a finding. Treat standard violations the same as checklist violations: assign a status of PRESENT, PARTIAL, or MISSING, plus severity and effort. Reference the specific standard file in each finding.

   After auditing each file individually, perform a **cross-file consistency check**:
   - **Design contradictions:** Does one module assume graceful degradation while another enforces a hard dependency? Does one file treat a field as optional while another treats it as required?
   - **Import chain side effects:** Trace import chains for module-level side effects like connections, env validation, or scheduled tasks. Would a missing env var crash the entire process at import time even though the feature claims graceful degradation?
   - **Configuration completeness:** Every new env var, dependency, or infrastructure requirement must be satisfiable in all environments: local dev, CI, staging, production. Check `.env.example`, Docker configs, CI pipelines, and IaC templates.
   - **Contract alignment:** Do types, field names, and data formats align across module boundaries? Does the API match what the consumer sends? Do error types thrown in one layer match what the caller catches?
   - **Behavioral symmetry:** If a resource is acquired, is it released on all code paths? If a feature is enabled, can it be disabled? If data is written, can it be read back consistently?

   In addition to the 71 checklist categories, also assess:

   - **README and presentation quality.** The README is the first thing a reviewer reads. Check: does it explain what the project does, how to set it up, how to run it, and how to test it? Are architecture decisions documented? Is there a clear project structure section? For interview submissions, a well-structured README with setup instructions, architecture explanation, and trade-off discussion can be the difference between an interview and a rejection. A missing or minimal README is a HIGH finding.
   - **Badges.** Run `python3 ~/.claude/tools/readme-badges.py <repo> --visibility <v> --release <r> --check`. Each README it names is a MEDIUM finding: the header carries a stale static version, a stack badge, a coverage number the build does not enforce, or a missing CI, release or license badge. Fix it with `--write`.

   - **AI slop.** A reviewer who meets generated filler in the README stops trusting the code behind it. Grade the step 5 scan, then read every README, doc and source comment for the shapes no detector decides: sections of uniform length, lists of exactly three, headings such as "Key Features" or "Future Work" with nothing under them, bold-label bullets standing in for sentences, and comments that restate the next line. Severity:
     - Search narration, chat residue or an unfilled placeholder in the README or the PR description is HIGH.
     - Any other tell in the README is MEDIUM.
     - A tell in another document or a commit message is LOW.
     - A prose comment in source is the comment-policy finding from [`../../rules/code-style.md`](../../rules/code-style.md), graded there.
     Never run or cite an AI-text detector score as evidence, per [`../../standards/anti-slop.md`](../../standards/anti-slop.md).

   - **Git history quality.** For interview submissions, commit history signals engineering discipline. Check: are commits logical and atomic, one concern per commit? Do messages follow conventional commit format? Is there a meaningful progression, infrastructure first, then core logic, then tests, then polish? A single "initial commit" with everything is a MEDIUM finding. Messy or meaningless commit messages are LOW.

   - **Dependency health and package selection.** Apply [`../../checklists/checklist.md`](../../checklists/checklist.md) category 13 for the baseline checks, justified, maintained, pinned, licensed, typed, better alternatives. Beyond that, also check assessment-specific concerns:
     - Is the runtime version the latest stable LTS, pinned with a version manager config file and `engines`, or equivalent in the package manifest?
     - Are there platform-specific issues such as native modules failing on Apple Silicon, or deprecated packages with no ARM64 support?
     - **Better alternatives signals**: no commits in 12+ months, open security issues, archived repository, missing type support when alternatives have it, large bundle size when a lighter option exists. Flag and include the replacement in the fix step.
     - **Type support completeness**: if using a typed language or superset, verify every dependency has type support (see step 6). Untyped dependencies in a typed codebase are a finding.

     Unjustified or heavy dependencies are LOW. Deprecated packages with maintained alternatives are MEDIUM. Known vulnerabilities are HIGH. Outdated runtime versions are MEDIUM.

   - **Developer tooling and enforcement.** The project must have automated code quality enforcement. Check for and add if missing:

     | Tool type | Purpose | Examples by ecosystem |
     |:----------|:--------|:---------------------|
     | Runtime version manager | Pin runtime version for all developers and CI | Prefer `mise` with `.mise.toml` (or `.tool-versions` for asdf compatibility). Legacy files mise still reads: `.node-version`, `.nvmrc`, `.python-version`, `.ruby-version`, `.terraform-version`. Rust uses `rust-toolchain.toml` |
     | EditorConfig | Consistent formatting across editors | `.editorconfig` with language-appropriate indent style/size, charset, end of line, trailing whitespace, final newline |
     | Formatter | Deterministic code formatting | JS/TS: Prettier. Python: Black, Ruff format. Go: gofmt. Rust: rustfmt. Ruby: RuboCop. Java: google-java-format. Elixir: mix format |
     | Linter | Static analysis, code quality | JS/TS: ESLint (strictest config). Python: Ruff, Flake8, Pylint. Go: golangci-lint. Rust: Clippy. Ruby: RuboCop. Java: Checkstyle, SpotBugs |
     | Type checker | Static type verification | TS: tsc. Python: mypy, pyright. Ruby: Sorbet. Elixir: Dialyzer |
     | Pre-commit hooks | Enforce quality before commit | JS/TS: husky + lint-staged. Python: pre-commit framework. Go/Rust/Ruby: lefthook or pre-commit |
     | Commit linter | Enforce conventional commits | commitlint, commitizen |
     | CI pipeline | Automated quality gate on every push and PR | GitHub Actions, GitLab CI, CircleCI, Jenkins |

     All tools must be configured at their **strictest** settings. Missing `.editorconfig` is MEDIUM. Missing formatter or linter is HIGH. Missing pre-commit hooks is MEDIUM. Missing CI pipeline is HIGH.

   For each finding, assign:

   **Status**: PRESENT, PARTIAL, or MISSING.

   **Severity**, for PARTIAL and MISSING only:
   - **CRITICAL**: data loss, security vulnerability, or correctness failure in production. Fix before shipping.
   - **HIGH**: resilience gap that causes outages under real-world conditions. Fix soon.
   - **MEDIUM**: performance, maintainability, or operational gap. Schedule for next iteration.
   - **LOW**: best practice not followed, but no immediate risk. Backlog.

   **Effort**, for PARTIAL and MISSING only:
   - **S**: hours. A focused change in 1-2 files.
   - **M**: a day. Touches 3-5 files, may need tests.
   - **L**: days. Cross-cutting change, new infrastructure, or significant refactor.
   - **XL**: week+. New system component, major architectural shift.

9. **Present the assessment.** Format the output as described below.

10. **Offer to fix.** After presenting the assessment, ask: "Want me to implement the missing patterns?" If yes, work through them by priority: all CRITICAL first, then HIGH, then MEDIUM. Within the same severity, prefer lower effort. Each fix gets its own commit.

**Cascading fix prediction.** Before implementing each fix, analyze what it could break:

- Would the fix change a function signature, breaking existing callers?
- Would the fix introduce a new dependency or startup requirement?
- Would the fix change error behavior that other code relies on?
- Would the fix require coordinated changes in files not part of the current finding?
- Would the fix behave differently across environments, dev vs production?

   If any answer is yes, address the downstream effects in the same fix. Do not create fixes that introduce new problems for the convergence loop to catch. Front-loading this analysis reduces the number of convergence iterations.

   **First, set up developer tooling** if missing: `.editorconfig`, formatter, Prettier, Black, gofmt, etc., linter

…(truncated)