Brutal Honest

brutal-honest

Ruthless expert analysis with evidence. No guessing, no hallucinating, no ego.

1. Read EVERY file before judging — SubAgents read files themselves; the Main Chat only reads config files for stack detection
2. file:line for EVERY finding — no evidence = no finding
3. Grep to verify before claiming a pattern is missing
4. If uncertain → ASK the user or RESEARCH — never guess
5. If something looks intentional → ASK, don't flag — one question too many > one false finding
6. NEVER invent findings — hallucinated findings are worse than no findings

Red Flags — STOP Immediately

If you catch yourself thinking any of these, STOP and correct:

Process Flow

/brutal-honest → Wizard (Phase 1) → Research (Phase 2) → Follow-Up Questions (Phase 3) → SubAgent Review (Phase 4) → Output (Phase 5) → Action Wizard (Phase 6) → Fix Cycle (Phase 7) → Summary (Phase 8)

Phase 1: Interactive Wizard

When the skill is invoked, present a 3-step wizard. Ask questions conversationally with numbered options. Prefer multiple choice when possible, open-ended is fine too.

Step 1 — What to Review

Ask the user (multiple selections allowed):

1. Security — OWASP, secrets, auth, input validation, AI security, dependency audit
2. Architecture & Code — File structure, dependencies, DRY, error handling, types, testing coverage
3. Performance — Core Web Vitals / frame budget, assets, caching, lazy loading, N+1 queries
4. UI/UX & Accessibility — WCAG 2.2, mobile/responsive, visual hierarchy, anti-AI-slop patterns

Or they can describe a custom focus area.

Step 2 — Review Settings

Ask two things:

Scope — What files should I review?

1. git diff only (Recommended) — only changed files since last commit
2. Entire project — all project files (max 30, prioritized by importance)
3. Specific files/folders — user specifies which files or directories

Stack — How should I detect your tech stack?

1. Auto-detect (Recommended) — check config files (package.json, go.mod, etc.) automatically
2. Manual override — user tells you which stack

Step 3 — After the Review

Ask the user (multiple selections allowed):

1. Fix Prompt — generate fix instructions grouped by severity
2. Feature Ideas — spawn a Feature Scout SubAgent that explores and suggests 3-5 implementable features
3. Verify Commits — run verification pipeline against recent git history
4. Review only (Recommended) — just the brutal review, no extras

Phase 2: Research + Discovery (automatic)

After the wizard completes, research runs automatically via SubAgents. The Main Chat stays lean — it only reads config files and builds a file list. All heavy reading is delegated.

Step 1: Stack Detection (Main Chat)

Read ONLY config files to detect the stack: package.json, go.mod, pyproject.toml, Cargo.toml, composer.json, etc. Use the Stack Detection table below. Do NOT read source files yet.

Step 2: File Collection (Main Chat)

Based on the scope selected in the wizard:

• git diff: Run git diff --name-only (or git diff HEAD --name-only for staged changes) → file path list
• Entire project: Glob for source files → file path list. Prioritize: 1) Config files 2) Entry points 3) Core logic. Max 30 files.
• Specific files: Use the user's specified paths → file path list

Output: A list of file paths. Do NOT read these files in the Main Chat.

Step 3: Dispatch SubAgents (parallel)

Launch TWO SubAgents in parallel (single message with multiple Agent tool calls):

File Scanner SubAgent:

• Receives: The file path list from Step 2
• Job: Read EVERY file on the list. For each file, produce:
  • Summary (1-2 sentences): What the file does, its role in the project
  • Suspicious patterns: Disabled features, commented-out code, unusual patterns, feature flags
  • Dependencies: Import statements, version references
• Return: Structured summary of all files + list of suspicious patterns for Phase 3

Web Research SubAgent:

• Receives: Stack info + dependency list from config files (read in Step 1)
• Job: Research everything the model cannot know from training data:
  • Current stable versions of all detected frameworks and major dependencies
  • Known CVEs for detected dependencies (always, not just for Security reviews)
  • API documentation for project-specific tools (e.g., Ollama API, specific SDKs)
  • Competitor implementations — how similar projects solve the same problems
  • Domain-specific patterns — best practices the model might not know
  • Anything uncertain — if the agent encounters something it's not confident about, it searches
• Principle: "If you can't be 100% sure from training data alone → search for it"
• Return: Research findings organized by topic

Step 4: Collect Results

Main Chat receives summaries from both SubAgents. These summaries (NOT raw file contents) are used for:

• Phase 3 follow-up questions (based on suspicious patterns)
• Phase 4 review agent context (summaries + research + file paths)

Phase 3: Informed Follow-Up Questions

After the File Scanner returns suspicious patterns, ask targeted questions based on REAL findings. Questions are asked one at a time in the chat.

Question Format

Ask each question as a numbered-option message. Every option MUST have a clear description explaining what it means and what happens if chosen:

Question 1/N: [Clear question about what was found]

1. **[Option label]** — [1-2 sentences explaining what this means and what the consequence is]
2. **[Option label]** — [1-2 sentences explaining what this means and what the consequence is]
3. **[Option label] (Recommended)** — [1-2 sentences explaining why this is recommended]

(Answer with the number, or ask if something is unclear)

When to Ask

Ask the user when the File Scanner found something that COULD be a deliberate decision:

• Disabled features — "Feature X is disabled via early return. Intentional?"
• Unusual patterns — "Found dangerouslySkipPermissions: true. On purpose?"
• Outdated versions — "[Framework] v[old] detected, current stable is v[new]. Flag as MAJOR?"
• Deactivated code — "Code block is commented out / feature-flagged off. Intended?"
• Security concerns — "Found [potential issue]. Deep security audit?"

Rules

1. ONE question per message — never batch multiple questions. Ask one, wait for the answer, then ask the next
2. Only ask about things the File Scanner ACTUALLY FOUND — never hypothetical questions
3. Every option has a description — no bare labels. The user must understand what each option means without reading code
4. Include (Recommended) on the option you'd suggest, based on what the Scanner found
5. If the user asks "what do you mean?" → explain the context in more detail and re-ask the same question. NEVER skip a question because the user didn't understand it
6. If nothing suspicious found → skip Phase 3 entirely — don't ask questions for the sake of asking
7. When in doubt: ASK — one unnecessary question is infinitely better than one false finding
8. Answers inform the review — intentional patterns are excluded from findings, confirmed bugs are flagged
9. Do NOT use the AskUserQuestion tool — ask in regular chat messages with numbered options

Phase 4: Parallel SubAgent Reviews

Spawn one SubAgent per selected review domain using the Agent tool. Only spawn agents for domains the user selected in Phase 1 Step 1. Launch ALL selected agents in parallel (single message with multiple Agent tool calls).

What Each Agent Receives

1. The relevant checklist section (pasted inline — NOT a file reference)
2. File paths to review (NOT file contents — agents read files themselves using the Read tool)
3. File Scanner summaries from Phase 2 (1-2 sentence context per file, so agents know what to focus on)
4. Research results from Phase 2 (framework versions, CVE findings, best practices, API docs)
5. User's answers from Phase 3 (what's intentional, what to ignore)
6. The Iron Rules (copied into every agent prompt)
7. Stack-specific checklist items for their domain

Agent Definitions

Security Agent

• Checklist: Security section from references/checklists.md
• Focus: OWASP top 10, hardcoded secrets, auth patterns, input validation, CSRF, dependency CVEs, AI security
• Must: Check every import, every API call, every user input handler, every env variable usage

Architecture & Code Agent

• Checklist: Architecture + Testing sections from references/checklists.md
• Focus: File structure, God objects/functions, circular dependencies, DRY violations, error handling, type safety, test coverage
• Must: Trace dependency graph, check module boundaries, verify error paths, assess test quality

Performance Agent

• Checklist: Performance section from references/checklists.md
• Focus: Core Web Vitals / frame budget, asset optimization, caching strategy, lazy loading, N+1 queries, bundle size
• Must: Check asset sizes, loading patterns, database queries, render paths, memory usage

UI/UX & Accessibility Agent

• Checklist: Accessibility section from references/checklists.md + references/ui-patterns.md
• Focus: WCAG 2.2, keyboard navigation, screen readers, mobile/responsive, visual hierarchy, anti-AI-slop patterns
• Must: Check semantic HTML, ARIA labels, color contrast, focus management, layout patterns
• Only spawn for web/mobile/game projects — skip for CLI tools, libraries, APIs without UI

Agent Prompt Template

Use this template when dispatching each agent via the Agent tool:

You are a {DOMAIN} review agent performing a brutal-honest code review.

## Iron Rules (non-negotiable)
1. Read EVERY file before judging — no exceptions
2. Include file:line for EVERY finding — no evidence = no finding
3. Use Grep to verify patterns before claiming they're missing
4. If uncertain → mark as "UNVERIFIED" and explain what you couldn't confirm (you cannot ask the user directly — only the lead agent can)
5. If something looks intentional → flag as "POSSIBLY INTENTIONAL" instead of a finding
6. NEVER invent findings — hallucinated findings are worse than no findings

## Your Checklist
{PASTE RELEVANT CHECKLIST SECTION}

## Stack-Specific Items
{PASTE STACK-SPECIFIC CHECKLIST ITEMS FOR THIS DOMAIN}

## Research Context
{PASTE FRAMEWORK VERSION + CVE + BEST PRACTICE FINDINGS FROM PHASE 2}

## User Clarifications
{PASTE PHASE 3 ANSWERS — what's intentional, what to ignore}

## Files to Review
{LIST OF FILE PATHS — you MUST read each file yourself using the Read tool before reviewing it}

## File Scanner Context
{PASTE 1-2 SENTENCE SUMMARIES PER FILE FROM PHASE 2 SCANNER — use these to prioritize, but always read the actual files}

## Instructions
Review every file against your checklist. For each finding report:
- **Severity:** CRITICAL / MAJOR / MEDIUM / MINOR (use severity guide definitions)
- **Location:** file:line
- **Issue:** What's wrong
- **Impact:** Why it matters
- **Fix:** Suggested fix (one sentence)

Report ONLY real findings backed by evidence. Zero tolerance for guessing.
DO NOT write any code or make any changes. Review and report only.

## Return Protocol

End your review with one of these statuses:

- **DONE** — Review complete, all findings have file:line evidence.
- **DONE_WITH_CONCERNS** — Review complete, but some areas couldn't be fully verified. List what and why.
- **NEEDS_CONTEXT** — Can't complete review without more information. List exactly what you need.
- **BLOCKED** — Can't review at all (files unreadable, wrong stack, etc.). Explain the blocker.

Phase 5: Aggregation + Output

After all SubAgents complete, aggregate their findings into a single review.

Step 1: Collect

Gather all findings from all review agents.

Step 2: Deduplicate

If multiple agents flagged the same issue, keep the most detailed finding and note which agents found it.

Step 3: Sort

Order by severity: CRITICAL → MAJOR → MEDIUM → MINOR

Step 4: Format Output

## BRUTAL REVIEW: [Topic]

**Stack:** [detected] | **Scope:** [diff/project/files] | **Agents:** [which ran]

### CRITICAL
- [Finding] — `file:line` — [why it matters]

### MAJOR
- [Finding] — `file:line` — [why it matters]

### MEDIUM
- [Finding] — `file:line`

### MINOR
- [Finding] — `file:line`

### VERDICT
One brutal sentence. No sugarcoating.

Omit empty severity sections. If no findings in a severity level, don't include that heading.

Phase 6: Action Wizard

After presenting the review, ask the user what to do next:

How do you want to handle the findings?

1. Fix via SubAgents (Recommended) — Phase-by-phase: Implement → Spec Review → Code Quality Review → Commit. Cheapest and most reliable.
2. Fix via Agent Teams — Same phase structure as SubAgents, but uses TeamCreate for parallel persistent agents. 3-5x more expensive in tokens.
3. Fix it yourself — I'll assist in chat but you drive the fixes.
4. Discuss first — Let's talk through the findings before deciding on action.

Phase 7: Fix Cycle

When "Fix via SubAgents" or "Fix via Agent Teams" is selected, group findings into phases by severity. For Agent Teams, use TeamCreate and assign tasks to persistent teammates instead of spawning fresh SubAgents per step — otherwise the phase structure is identical.

• Phase 1: CRITICAL fixes (must fix immediately)
• Phase 2: MAJOR fixes (ship blockers)
• Phase 3: MEDIUM + MINOR fixes (combined, lowest priority)

Skip empty phases. If no CRITICAL findings, start with Phase 2.

Create all phase tasks upfront using TaskCreate. One task per phase (e.g. "Phase 1: CRITICAL fixes", "Phase 2: MAJOR fixes", "Phase 3: MEDIUM + MINOR fixes"). Set blockedBy so Phase 2 is blocked by Phase 1, Phase 3 is blocked by Phase 2. Then work through them in order — mark each as in_progress when starting, completed when done. This gives the user a clear progress view.

Never skip findings without asking the user. Fix ALL findings in each phase. If you think a finding should be skipped (e.g. "cosmetic", "by design", "app-wide"), ask the user first — don't decide on your own. The user confirmed these findings during the review; skipping them silently wastes that decision.

Per Fix Phase

Step 1: Implementer SubAgent

Spawn via Agent tool:

• Receives: All findings for this severity phase (Severity + file:line + Issue + Impact + Fix) and the relevant file paths
• Does NOT receive file contents — reads files itself using the Read tool
• Job: Implement each fix, write tests where appropriate, commit changes, self-review
• Must follow Iron Rules: read files before changing, verify fixes work

Include in the agent prompt:

## Before You Begin

If you have questions about requirements, approach, or scope — ask them now.
Raise any concerns before starting work.

## While You Work

If you encounter something unexpected or unclear — ask, don't guess.

## Return Protocol

End your work with one of these statuses:

- **DONE** — All fixes implemented and verified.
- **DONE_WITH_CONCERNS** — Fixes implemented but I have concerns about [X]. Review carefully.
- **NEEDS_CONTEXT** — Can't complete without more information: [what you need].
- **BLOCKED** — Can't proceed: [blocker]. Do NOT force a bad fix.

## When You're in Over Your Head

It is always OK to stop and say "this is too hard for me."
Bad work is worse than no work. You will not be penalized for escalating.

Step 2: Spec Review SubAgent

Spawn via Agent tool after Implementer completes:

• Receives: Original findings for this phase + Implementer's report + relevant file paths
• Does NOT receive file contents — reads files itself using the Read tool
• Job: Verify EACH finding is actually fixed by reading the actual code
• Does NOT trust the Implementer's claims — reads code independently
• Checks: Was the finding addressed? Is the fix correct? Were any findings missed?
• Uses the same Return Protocol (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED)
• ✅ All fixed → proceed to Step 3
• ❌ Issues found → describe what's wrong → Implementer fixes → Spec Review re-runs

Step 3: Code Quality Review SubAgent

Spawn via Agent tool after Spec Review passes:

• Receives: git diff of all changes in this phase
• Job: Verify fix quality — no new bugs, no regressions, clean code, consistent style
• Uses the same Return Protocol (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED)
• ✅ Approved → proceed to Verification Gate
• ❌ Issues found → describe what's wrong → Implementer fixes → Code Quality re-reviews

Step 4: Verification Gate (mandatory)

Before committing and moving to the next phase:

1. Run the project's test/build/lint command (auto-detect from package.json scripts, Makefile, Cargo.toml, etc.)
2. Read the full output, check exit code
3. If tests fail → the fix broke something. Re-dispatch Implementer with the failure context
4. If no test command exists → at minimum run syntax check (node --check, go vet, cargo check, python -m py_compile, etc.)
5. Only proceed when verification passes

Step 5: Commit + Push

After verification passes, ensure all changes are committed and pushed. Then proceed to next severity phase.

Handling Agent Status

After each SubAgent returns, check its status:

• DONE → proceed to next step
• DONE_WITH_CONCERNS → review the concerns, decide if they're blocking or acceptable, note them for the user
• NEEDS_CONTEXT → provide the missing context and re-dispatch the same agent
• BLOCKED → assess the blocker:
  1. Context problem → provide more context, re-dispatch
  2. Task too complex → break into smaller pieces, re-dispatch
  3. Plan itself is wrong → escalate to user, ask how to proceed

Never ignore a BLOCKED status. Never force-retry without changes.

Feature Scout (if selected in Phase 1 wizard)

After all fix phases complete (or after review-only), spawn a separate SubAgent:

• Explores the entire project: structure, patterns, features, architecture
• Suggests 3-5 concrete, implementable features
• Each suggestion includes: what it does, why it adds value, rough complexity (small/medium/large)
• Presents suggestions for the user to pick favorites

Verify Commits (if selected in Phase 1 wizard)

Run verification against recent git history:

• Detect phases from commit subjects (pattern matching)
• Extract plan items from commit bodies
• Check: existence + correctness, cross-references, regressions
• Report as verification table with pass/fail per item

Phase 8: Final Summary

After all phases complete, present a human-readable summary of everything.

Summary Content

• What was reviewed (scope, stack, which domains)
• What was found (count per severity, key issues in plain language)
• What was fixed (if fix cycle ran)
• What remains open (if anything was skipped or deferred)

No line numbers in the summary. Write in human words, not technical jargon. Example:

"Reviewed the full Aria project (Electron + React). Found 2 critical security issues (hardcoded endpoint exposed to network, missing CSP headers), 5 major architecture problems, and 8 minor code style issues. All critical and major issues fixed and committed. Minor issues left as-is per your decision."

Final Question

Ask the user:

What now?

1. Another review — review a different project or set of files
2. Re-review same files — check if everything is clean after fixes
3. Done — finished, end the review session

Stack Detection (Step 0 — before analysis)

Detect the project's tech stack before applying any checklist. This determines which severity items and checklist sections are relevant.

Important: Only apply stack-specific items when that stack is detected. A Python API does not get React checklist items. A vanilla HTML game does not get Next.js items.

Multi-stack projects: If multiple config files are detected (e.g., package.json + pyproject.toml in a monorepo), apply ALL matching stack-specific checklists. Review each sub-project against its own stack.

Input Handling

Context Awareness: Check for framework config files (package.json, pyproject.toml, go.mod, etc.) to detect versions. Flag outdated framework versions (2+ major versions behind current stable). (Exception: game engines — LTS versions are standard; only flag end-of-life or unsupported versions.) Check current stable version of the detected framework using available tools or training knowledge — flag anything 2+ major versions behind; if unable to verify, state the assumption.

Files/Folders:

• Single file: Read it
• Multiple files:
  • Glob: Use pattern appropriate to detected stack. Default: **/*.{js,ts,jsx,tsx,vue,svelte,astro,html,css,py,go,rs,java,kt,php,rb,cs,dart,swift,ex,exs,cpp,hpp,c,h,erl,gd,tscn,tres,unity,uproject,lua}
  • Prioritize: 1) Config files (package.json, pyproject.toml, go.mod, etc.) 2) Entry points 3) Core logic
  • Max 30 files: If more, analyze entry points + configs only
  • Monorepos: If >3 config files detected at different paths, treat as multi-project. Analyze workspace root config + one entry point per sub-project. Distribute the 30-file limit proportionally. When user specifies a sub-project, focus on that one.
• Images: Use Read tool to analyze screenshots/mockups for colors, contrast, typography, spacing, layout issues. Supports PNG, JPG, WebP. If no image provided, skip.

Reference Loading

STEP 1: Locate Skill Directory

• Try reading from skill installation path: ./references/[file]
• Check your AI tool's skill/plugin directory for the references/ folder (e.g., ~/.claude/skills/brutal-honest/references/, project-level .agents/skills/brutal-honest/references/, or equivalent)

STEP 2: Attempt to Load (in order)

1. references/severity-guide.md → If NOT FOUND, use "Embedded Severity Guide" below
2. references/checklists.md → If NOT FOUND, use "Embedded Checklists" below
3. references/ui-patterns.md → If NOT FOUND, use "Embedded UI Patterns" below

STEP 3: If files found, external overrides embedded; fill gaps with embedded defaults

• External files OVERRIDE embedded defaults (for customization)
• If external incomplete, fill gaps with embedded

Embedded Severity Guide (Fallback)

These embedded sections are fallbacks only. If you have the references/ folder installed, the external files take priority and these are ignored.

Use this if references/severity-guide.md not found.

CRITICAL - Fix yesterday

• AI vulnerabilities — Prompt injection (user input reaches LLM unsanitized), AI tools with DELETE permissions without confirmation, auth tokens in AI conversation logs
• Security — Hardcoded secrets, SQL injection, XSS, CSRF without protection, no input validation at system boundaries
• Accessibility — WCAG 2.2 violations = legal risk
• Stability — Crashes, infinite loops, memory leaks, unhandled exceptions in critical paths
• Data loss — No backups, no transaction safety, destructive operations without confirmation
• Soft-lock — Player cannot progress and cannot load a prior save (game projects)
• Save corruption — Save data can be lost or corrupted without detection/recovery (game projects)
• Determinism failure — Desyncs in multiplayer from non-deterministic simulation (multiplayer games)

MAJOR - Ship blocker

• Outdated framework — Using a version 2+ major versions behind current stable release (check against latest stable, not a hardcoded version number; for game engines: locking to an LTS version is standard; flag only if engine version is end-of-life or unsupported)
• Architecture — 2000+ line files without clear section separation (unless architecturally intentional, e.g., single-file apps, embeddable widgets, Go's copy-over-dependency idiom), God objects/functions, circular dependencies
• Type safety — No strict mode (where language supports it), any/object/interface{} everywhere at boundaries
• UX — No loading states, broken mobile/responsive, no error feedback to users
• AI Architecture — Client-side LLM calls instead of server-side (exposes API keys)
• Framework-specific rendering errors — Hydration mismatches (SSR frameworks), template compilation errors, runtime binding failures
• Missing error handling — No try/catch in async operations, silent failures, unhandled promise rejections / panics / exceptions
• No object pooling — Frequently spawned objects (bullets, particles, enemies) allocated/destroyed per frame causing GC pauses (game projects)
• Wrong update loop — Physics in render loop or rendering in physics loop, causing frame-rate-dependent behavior (game projects)
• No frame budget discipline — No profiling, no performance targets, frame time exceeds 16.6ms in core gameplay (game projects)
• No worker offloading — Heavy simulation running on main thread blocking rendering; use Web Worker for game logic, transferable ArrayBuffers for data (web game projects with large entity counts)

MEDIUM - Code review nightmare

• Not using framework idioms — Not leveraging the framework's recommended patterns and latest stable features
• Performance — No image/asset optimization, missing lazy loading, no caching strategy
• Missing tests — No unit tests, no integration tests for critical paths
• No CI/CD — No automated builds, no linting on PR, manual deployments (lower priority for solo/indie/game jam projects)
• State management — Prop drilling / global mutation / spaghetti state where framework provides better patterns (game singletons like GameManager/AudioManager are standard architecture, not spaghetti)
• AI-generated aesthetic — Generic design with no brand identity: purple gradients, single sans-serif font, three-column icon grids, uniform rounded corners, 0.1 opacity shadows on everything (web projects)
• Missing keyboard navigation — No keyboard shortcuts for power users (where applicable)
• No monitoring — No error tracking, no performance monitoring, no logging strategy
• No input rebinding — Hardcoded controls with no remapping option (game projects — accessibility baseline)
• No game accessibility — Missing colorblind mode, subtitles, or difficulty options (game projects — 2026 baseline)
• No spatial partitioning — Brute-force collision detection with many entities, no quadtree/octree/spatial hash (game projects)

MINOR - Nitpick, but fix it

• Inconsistent code style — Mixed formatting, naming conventions, quote styles within the same file
• Missing documentation — Public APIs / exported functions without types or docs
• Debug code in production — console.log, print(), debug flags, TODO comments left in shipped code
• Non-semantic markup — div soup, inline styles (web projects)
• Inconsistent naming — Mixed camelCase/snake_case, unclear variable names
• Audio mixing issues — No separate volume controls for music/SFX/dialogue, or sound clipping from too many simultaneous voices (game projects)

Embedded Checklists (Fallback)

Use this if references/checklists.md not found.

Universal Checklist (applies to ALL projects)

Security:

• No secrets in code — API keys, tokens, passwords in env vars / secret manager only
• Input validation — Validate at system boundaries (user input, external APIs, file uploads)
• Injection prevention — ORM / parameterized queries / sanitized output (SQL, XSS, command injection)
• Dependency audit clean — No known CVEs
• CSRF protection — Anti-forgery tokens or SameSite cookies (web apps)
• Auth best practice — OAuth 2.1, OIDC, or framework-recommended auth patterns
• AI security (if applicable) — Prompt injection prevention, LLM output sanitization, AI tool permissions gated

Performance:

• Appropriate for platform — Web: Core Web Vitals (LCP ≤2.5s, INP ≤200ms, CLS ≤0.1) | Games: 60fps (16.6ms frame budget), consistent frame pacing | Mobile: startup <2s | API: p95 <200ms
• Asset optimization — Images (modern formats), fonts (font-display: swap), bundle sizes appropriate for target
• Caching strategy — HTTP caching, application-level caching, CDN where appropriate
• Lazy loading — Below-fold content, heavy dependencies, routes/pages loaded on demand (not applicable to games)
• No unnecessary computation — Database queries optimized, N+1 queries eliminated, pagination for large datasets

Architecture:

• Separation of concerns — No God objects/functions, clear module boundaries
• Clean dependency graph — No circular dependencies, clear import direction
• DRY without over-abstraction — Repeated code extracted, but no premature abstraction
• Error handling — Graceful failures, user-facing error messages, structured logging
• Configuration management — Environment-specific config separated from code
• Database patterns — Connection pooling, migrations versioned, proper ORM usage (if applicable)

Testing:

• Unit tests — Core business logic covered with meaningful assertions
• Integration tests — Critical paths tested (API endpoints, database operations, auth flows)
• E2E tests — Key user flows covered (where applicable)
• Test isolation — Tests don't depend on external services or shared state
• Coverage strategy — Coverage thresholds defined for critical modules (not vanity 100%)
• Mocking boundaries — External services mocked at integration boundary, not deep internals
• Test naming — Test names describe behavior, not implementation

CI/CD:

• Automated builds — Build runs on every PR
• Linting/formatting — Enforced in CI, not just local
• Tests run on PR — Failing tests block merge
• Deployment strategy — Automated deploy with rollback capability

Accessibility (web/mobile):

• WCAG 2.2 compliance — Focus rings, keyboard navigation, screen reader support
• Semantic markup — Correct elements for their purpose (button not div, nav not div, etc.)
• ARIA labels — Interactive elements accessible, landmarks defined
• Color contrast — 4.5:1 minimum for normal text, 3:1 for large text
• Reduced motion — Respect prefers-reduced-motion
• Focus management — Focus trap in modals, return focus on close

Stack-Specific (applied ONLY when detected)

React/Next.js: RSC usage, Server Actions, React 19+ hooks (useActionState, useOptimistic), PPR, App Router patterns, error.tsx + loading.tsx Vue/Nuxt: Composition API, auto-imports, Nuxt 4 patterns, defineModel, Pinia stores Svelte/SvelteKit: Runes ($state, $derived, $effect), $props() for component props, server load functions, form actions Angular: Signals, standalone components, zoneless change detection, control flow (@if, @for) Python: Type hints (3.13+), async patterns (Django, FastAPI), proper ORM usage, virtual environments Go: Error handling patterns (errors.Is/As), goroutine management, interfaces, go vet/staticcheck Rust: Ownership patterns, error handling (Result/Option), unsafe audit, clippy clean PHP/Laravel: Eloquent patterns, middleware, queue patterns, Laravel 12 features Astro: Content Collections, island architecture, zero-JS by default, View Transitions Remix: Loaders/actions, nested routes, progressive enhancement, error boundaries SolidJS: Fine-grained signals, no virtual DOM, createResource, JSX without re-renders Hono: Web Standards (Request/Response), middleware chains, edge-first, multi-runtime Ruby/Rails: Active Record patterns, concerns, Hotwire/Turbo, N+1 prevention, Rails 8 conventions Elixir/Phoenix: OTP/GenServer patterns, LiveView, fault tolerance, supervision trees C/C++: RAII, smart pointers, memory safety, modern C++20/23, no raw new/delete Swift: Structured concurrency (async/await, actors), protocol-oriented design, SwiftUI vs UIKit Kotlin: Coroutines, null safety, multiplatform patterns, sealed classes, Flow Java / Kotlin (JVM): Spring Boot dependency injection, JPA/Hibernate entity mapping, N+1 prevention, modern Java (records, sealed classes, virtual threads), JUnit 5 + Mockito C# / .NET: Project architecture (web API / Blazor / WPF / MAUI), Entity Framework Core with migrations, async/await with cancellation tokens, nullable reference types enabled, dependency injection lifetimes Vanilla HTML/JS/CSS: Progressive enhancement, semantic HTML, no-build patterns, Web Standards Mobile (React Native / Flutter / SwiftUI): Platform conventions (iOS HIG / Material Design), framework navigation, appropriate state management, 60fps scrolling, VoiceOver/TalkBack support Unity: Game loop separation (FixedUpdate/Update), object pooling, DOTS/ECS for data-heavy systems, Addressables, draw call batching Unreal Engine: UPROPERTY/UFUNCTION macros, Blueprint vs C++ separation, Nanite/Lumen usage, PCG framework, actor lifecycle Godot: Process separation (_physics_process/_process), signal patterns, Jolt physics (4.6+), @export variables, scene composition Phaser/Web 2D: Scene lifecycle, sprite batching via texture atlases, audio context gesture handling, object pooling, WebGL context management Three.js/Web 3D: WebGPU with WebGL 2 fallback, InstancedMesh for repeated geometry, dispose() for GPU memory, frame budget with delta time, frustum culling + LOD Bevy: ECS architecture, Required Components (0.15+), AssetServer loading, plugin architecture, system scheduling with .before()/.after() Pygame/Love2D: Fixed timestep game loop, assets loaded once at init, input abstraction with rebinding, no per-frame allocations, game state machine Web Canvas Game: Worker thread offloading (sim in Worker, render on main), zero-copy ArrayBuffer transfer, TypedArray hot data (Int32Array/Float32Array for counters and spatial indices), adaptive quality auto-tuning, GC-free hot path (ring buffers, object pooling, swap-and-pop, dirty tracking)

Embedded UI Patterns (Fallback)

Use this if references/ui-patterns.md not found.

Layout Architecture

• Bento Grid (Asymmetric): Visual hierarchy through size, not symmetry
• View Transitions API: Same-document (startViewTransition()) + cross-document (@view-transition { navigation: auto; })
• Anchor Positioning: CSS anchor-name + position-area for popovers without JS

Anti-AI-Slop Signals

• Red flags: purple/indigo gradients, single sans-serif font (Inter/Roboto), three-column icon grids, generic CTAs, uniform rounded corners, 0.1 opacity shadows everywhere
• Professional signals: intentional font pairing (serif+sans or display+body), semantic color system via CSS custom properties, 8px spacing grid, benefit-driven CTA language, social proof near decision points

Visual Hierarchy

• 60-30-10 Color Rule: 60% neutral, 30% primary, 10% accent
• Semantic Color System: CSS custom properties with semantic names (--text-primary, --surface, --accent), light-dark() for dark mode, `color-mix

…(truncated)