# Brutal Honest
> Use when user wants honest, evidence-backed code review. Every finding requires file:line proof. Covers security, architecture, performance, UI/UX for 33+ tech stacks.
- Skill: `majiayu000/brutal-honest` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/brutal-honest`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/brutal-honest/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/brutal-honest
---
# brutal-honest
Ruthless expert analysis with evidence. No guessing, no hallucinating, no ego.
## Iron Rules (non-negotiable, every phase)
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:
| Thought | Reality |
|---------|---------|
| "I'll just skim this file" | Read it fully or don't review it |
| "This pattern is probably missing" | Grep first. No grep = no claim |
| "The file is too large to read" | Read it in chunks. Size is not an excuse |
| "I'm confident without checking" | Confidence without evidence = hallucination |
| "This is obviously wrong" | Obvious to whom? Verify with code |
| "I'll flag it just in case" | No evidence = no finding. Period |
| "The user probably knows about this" | If it's a real finding, report it with evidence |
| "I don't need to research this" | If uncertain about versions/CVEs/patterns — research |
| "I'll paste file contents to the SubAgent" | SubAgents have Read tool access. Send paths, not contents |
## 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
The Web Research SubAgent is MANDATORY. It ALWAYS runs, even for small projects. At minimum it checks current stable versions of detected dependencies. The "when uncertain" trigger from v3.1 was too passive — agents never triggered it. Now it's mandatory.
### 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
Do NOT claim fixes are complete without running verification. Do NOT commit broken code.
**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.
| File Found | Stack | Checklist Focus |
|---|---|---|
| `package.json` with `"react"` | React/Next.js | React-specific + Universal |
| `package.json` with `"vue"` | Vue/Nuxt | Vue-specific + Universal |
| `package.json` with `"svelte"` | Svelte/SvelteKit | Svelte-specific + Universal |
| `package.json` with `"@angular"` | Angular | Angular-specific + Universal |
| `requirements.txt` / `pyproject.toml` with `django` | Python (Django) | Python (Django) + Universal |
| `requirements.txt` / `pyproject.toml` with `fastapi` | Python (FastAPI) | Python (FastAPI) + Universal |
| `requirements.txt` / `pyproject.toml` (no django/fastapi) | Python (generic) | Universal only |
| `go.mod` | Go | Go-specific + Universal |
| `Cargo.toml` | Rust | Rust-specific + Universal |
| `composer.json` | PHP/Laravel | PHP-specific + Universal |
| `pom.xml` / `build.gradle` | Java/Kotlin | JVM-specific + Universal |
| `*.csproj` / `*.sln` | C#/.NET | .NET-specific + Universal |
| `pubspec.yaml` | Flutter/Dart | Flutter-specific + Mobile + Universal |
| `astro.config.*` | Astro | Astro-specific + Universal |
| `package.json` with `"@remix-run"` | Remix | Remix-specific + Universal |
| `package.json` with `"solid-js"` | SolidJS | Solid-specific + Universal |
| `package.json` with `"hono"` | Hono | Hono-specific + Universal |
| `Gemfile` with `rails` | Ruby/Rails | Rails-specific + Universal |
| `mix.exs` | Elixir/Phoenix | Elixir-specific + Universal |
| `CMakeLists.txt` / `*.cpp` + `Makefile` | C/C++ | C/C++-specific + Universal |
| `Package.swift` / `*.xcodeproj` | Swift/iOS | Swift-specific + Mobile + Universal |
| `build.gradle.kts` with `kotlin` | Kotlin (native/multiplatform) | Kotlin-specific + Universal |
| `*.html` (standalone, no framework) | Vanilla HTML/JS/CSS | Web standards + Universal |
| `package.json` with `"react-native"` | React Native | Mobile + Universal |
| `Assets/` + `ProjectSettings/` + `*.unity` | Unity | Unity-specific + Game + Universal |
| `*.uproject` | Unreal Engine | Unreal-specific + Game + Universal |
| `project.godot` | Godot | Godot-specific + Game + Universal |
| `package.json` with `"phaser"` | Phaser | Phaser-specific + Game + Universal |
| `package.json` with `"three"` | Three.js | Three.js-specific + Game + Universal |
| `package.json` with `"pixi.js"` | PixiJS | Phaser/Web 2D-specific + Game + Universal |
| `package.json` with `"kaplay"` | Kaplay | Phaser/Web 2D-specific + Game + Universal |
| `Cargo.toml` with `bevy` | Bevy | Bevy-specific + Game + Universal |
| `conf.lua` + `main.lua` | Love2D | Love2D-specific + Game + Universal |
| `*.py` with `import pygame` | Pygame | Pygame-specific + Game + Universal |
| `*.html` with `