cmp-standards 3.7.0 → 3.8.1

package/templates/commands/experts.md

@@ -1,138 +1,375 @@
-## /experts - AI Code Review System
+---
+name: experts
+description: Multi-expert code review with rigorous logical reasoning and evidence-based consensus
+arguments:
+  - name: target
+    description: Files, directories, or task description to review
+    required: true
+  - name: --only
+    description: Comma-separated list of experts to include (security,performance,architecture,ux,database)
+    required: false
+  - name: --verbose
+    description: Show full reasoning chains from each expert
+    required: false
+  - name: --confidence
+    description: Minimum confidence level for findings (CERTAIN,HIGH,MEDIUM)
+    default: MEDIUM
+    required: false
+---
+
+# /experts - Evidence-Based Code Review System
 
-> **Purpose**: Multi-expert code review with consensus voting
-> **Usage**: `/experts [files or task description]`
+> **Framework**: All experts use `_reasoning-framework.md` for rigorous logical analysis.
+
+Execute this multi-phase expert review following the logical sequence below.
 
 ---
 
-## Overview
+## PHASE 1: PRE-ANALYSIS (Mandatory First Step)
+
+Before invoking ANY expert, complete these checks:
+
+### 1.1 Target Resolution
+```
+TASK: Resolve $ARGUMENTS.target to actual files
+
+STEPS:
+1. IF target is file path → Verify file exists
+2. IF target is directory → Glob for relevant files (.ts, .tsx, .js, .jsx)
+3. IF target is description → Search codebase for relevant files
+4. IF no files found → STOP with clear error message
+
+OUTPUT:
+- files_to_review: [list of absolute paths]
+- total_lines: [estimated line count]
+- file_types: [breakdown by extension]
+```
 
-The `/experts` command launches a panel of AI experts to review your code:
+### 1.2 Criticality Assessment
+```
+PREMISE: IF code_touches_critical_domain THEN requires_unanimous_approval
+
+CRITICAL DOMAINS (search for these patterns):
+- Authentication: auth, login, session, token, jwt, oauth
+- Authorization: permission, role, access, admin, rbac
+- Financial: payment, stripe, invoice, billing, transaction
+- Data: migration, schema, DROP, ALTER, DELETE
+- Security: password, secret, encrypt, hash, sanitize
+
+ASSESSMENT:
+1. Grep target files for critical patterns
+2. Count matches per domain
+3. Determine criticality level
+
+OUTPUT:
+- criticality: CRITICAL | NORMAL
+- critical_domains_found: [list with file:line references]
+- reasoning: "Found X pattern at Y location, therefore Z"
+```
 
-1. **Security Expert** - SQL injection, auth, input validation
-2. **Performance Expert** - Waterfalls, N+1, lazy loading
-3. **Architecture Expert** - Types, modules, SOLID principles
-4. **UX Expert** - Accessibility, mobile-first, design tokens
-5. **Database Expert** - Schema, migrations, queries
-6. **Memory Expert** - Pattern detection, auto-improvement
+### 1.3 Expert Selection
+```
+PREMISE: Select experts based on actual file content, not assumptions
+
+DETECTION RULES:
+- Security Expert: IF (user input handling OR auth code OR data validation)
+- Performance Expert: IF (loops OR async/await OR database queries OR React components)
+- Architecture Expert: IF (type definitions OR imports OR module structure)
+- UX Expert: IF (JSX/TSX OR CSS OR component files)
+- Database Expert: IF (schema files OR query builders OR migrations)
+- Memory Expert: ALWAYS (observes patterns)
+- Documentation Expert: IF (public API changes)
+
+PROCESS:
+1. Read first 100 lines of each file
+2. Detect patterns matching each expert's domain
+3. Select experts with HIGH confidence of relevance
+4. IF --only flag provided, override with specified experts
+
+OUTPUT:
+- selected_experts: [list with selection reasoning]
+- excluded_experts: [list with exclusion reasoning]
+```
 
 ---
 
-## Usage Examples
+## PHASE 2: PARALLEL EXPERT EXECUTION
 
-```bash
-# Review specific file
-/experts src/components/UserForm.tsx
+Launch selected experts in parallel using the Task tool.
 
-# Review directory
-/experts src/server/api/routers/
+### 2.1 Expert Invocation Template
 
-# Review with context
-/experts "Review the new authentication flow"
+For EACH selected expert, invoke with this prompt structure:
+
+```
+You are the {EXPERT_NAME} reviewing these files: {FILE_LIST}
+
+MANDATORY: Follow the reasoning framework in _reasoning-framework.md
+
+FOR EACH FINDING:
+1. OBSERVE: Quote exact code with file:line
+2. STATE PREMISE: "IF [condition] THEN [consequence]"
+3. VERIFY: Show what you searched and found
+4. FALSIFY: Ask "What would make this NOT an issue?"
+5. CONCLUDE: State confidence level and severity
+
+CONFIDENCE REQUIREMENTS:
+- CERTAIN: Direct observation, reproducible
+- HIGH: Pattern match + context verified
+- MEDIUM: Pattern match, some gaps
+- LOW: Inference only (cannot trigger REJECT)
+
+OUTPUT FORMAT (JSON):
+{
+  "expert": "{EXPERT_NAME}",
+  "vote": "APPROVE|REJECT|ABSTAIN",
+  "overall_confidence": "CERTAIN|HIGH|MEDIUM|LOW|UNKNOWN",
+  "search_log": {
+    "patterns_searched": [],
+    "files_checked": [],
+    "coverage_percent": 0
+  },
+  "findings": [
+    {
+      "severity": "critical|high|medium|low",
+      "confidence": "CERTAIN|HIGH|MEDIUM|LOW",
+      "file": "path",
+      "line": 0,
+      "observation": "what I saw",
+      "premise": "IF X THEN Y",
+      "verification": "how I confirmed",
+      "falsification": {"question": "", "status": "verified|disproven|uncertain"},
+      "message": "description",
+      "fix": "specific fix"
+    }
+  ],
+  "summary": "brief summary with confidence qualification"
+}
+```
+
+### 2.2 Parallel Execution
+```
+EXECUTE: Launch all selected experts simultaneously using Task tool
+TIMEOUT: 60 seconds per expert
+FALLBACK: If expert times out, record as ABSTAIN with reason
 ```
 
 ---
 
-## How It Works
+## PHASE 3: RESULT SYNTHESIS
+
+After all experts complete, synthesize results with logical reasoning.
 
+### 3.1 Confidence Aggregation
+```
+FOR EACH expert_result:
+  - Extract vote and confidence
+  - Extract all findings with severity >= $ARGUMENTS.confidence
+  - Discard findings with confidence < $ARGUMENTS.confidence
+
+AGGREGATE:
+  - total_findings: count of valid findings
+  - high_confidence_issues: findings where confidence >= HIGH AND severity >= HIGH
+  - uncertain_findings: findings where confidence = MEDIUM or status = uncertain
 ```
-1. ANALYZE CODE
-   • Detect criticality (CRITICAL vs NORMAL)
-   • Select relevant experts
 
-2. PARALLEL REVIEW (30-45 seconds)
-   • Each expert reviews independently
-   • Generates vote and findings
+### 3.2 Conflict Detection
+```
+PREMISE: IF expert_A_says_X AND expert_B_says_NOT_X THEN conflict
 
-3. CONSENSUS VOTING
-   • CRITICAL: Unanimity required (0 REJECT)
-   • NORMAL: Majority required (3/5 APPROVE)
+CHECK FOR:
+- Same file, conflicting assessments
+- Same pattern, different severity ratings
+- Contradicting recommendations
 
-4. RESULT
-   • APPROVED → Verification runs
-   • REJECTED → Detailed feedback provided
+FOR EACH conflict:
+  - Document both positions
+  - Identify which has higher confidence
+  - Flag for human review if equal confidence
+```
+
+### 3.3 Voting Logic
+```
+IF criticality = CRITICAL:
+  REQUIRE: Unanimous approval (0 REJECT votes)
+  LOGIC: ALL(votes == APPROVE OR votes == ABSTAIN)
+
+IF criticality = NORMAL:
+  REQUIRE: Majority approval
+  LOGIC: COUNT(APPROVE) > COUNT(REJECT)
+
+VOTE WEIGHTING:
+- ABSTAIN votes do not count toward total
+- REJECT with confidence = LOW is logged but doesn't block
+- REJECT with confidence >= HIGH blocks approval
+
+FINAL_DECISION:
+  IF voting_requirement_met AND no_high_confidence_rejects:
+    decision = APPROVED
+  ELSE:
+    decision = REJECTED
+    blocking_reasons = [list of high-confidence rejects]
 ```
 
 ---
 
-## Criticality Detection
+## PHASE 4: OUTPUT GENERATION
 
-Code is **CRITICAL** if it involves:
-- Authentication/Authorization
-- Financial operations
-- Database schema changes
-- External payment integrations
+Generate structured output with full reasoning chain.
 
-Critical code requires **unanimous approval** (no REJECT votes).
+### 4.1 Summary Header
+```markdown
+## Expert Review Results
 
----
+| Metric | Value |
+|--------|-------|
+| Files Reviewed | {count} |
+| Lines Analyzed | {count} |
+| Criticality | {CRITICAL/NORMAL} |
+| Experts Invoked | {list} |
+| Review Duration | {time} |
+```
 
-## Expert Responsibilities
+### 4.2 Voting Summary
+```markdown
+## Voting Summary
 
-| Expert | Checks | Rejects On |
-|--------|--------|------------|
-| Security | SQL injection, auth, validation | Any security hole |
-| Performance | N+1, waterfalls, bundle size | Critical perf issues |
-| Architecture | Types, modules, SOLID | Type violations |
-| UX | A11y, mobile, tokens | Missing accessibility |
-| Database | Schema, migrations | Data loss risk |
-| Memory | Patterns | Never (ABSTAIN) |
+Decision: {APPROVED ✅ / REJECTED ❌}
+Requirement: {Unanimous / Majority}
 
----
+| Expert | Vote | Confidence | Key Finding |
+|--------|------|------------|-------------|
+| Security | APPROVE | HIGH | No SQL injection detected |
+| Performance | REJECT | CERTAIN | N+1 query at users.ts:45 |
+| ... | ... | ... | ... |
+
+Reasoning Chain:
+1. [Expert votes and confidence levels]
+2. [Voting requirement check]
+3. [Final decision with justification]
+```
 
-## Output Example
+### 4.3 Findings Detail (if --verbose or REJECTED)
+```markdown
+## Detailed Findings
 
+### Finding 1: [Title]
+- **Expert**: Performance
+- **Severity**: HIGH
+- **Confidence**: CERTAIN
+- **Location**: `src/api/users.ts:45`
+
+**Observation**:
+```typescript
+// Exact code quoted
 ```
-## Expert Review
-Files: 1
-Criticality: NORMAL
-Experts: Security, Performance, Architecture, UX (4)
 
-[30 seconds - parallel review]
+**Premise**: IF query_in_loop AND n > 20 THEN performance_issue
+
+**Verification**:
+- Searched: forEach, map, for patterns with await
+- Found: Query inside forEach iterating over users array
+- Estimated iterations: 50 per page load
+
+**Falsification**:
+- Question: "Is this loop executed rarely?"
+- Answer: No, called on every dashboard load
+- Status: Verified issue
+
+**Fix**:
+```typescript
+// Specific fix with code
+```
+```
 
-✅ APPROVED (4/4)
-  Security: ✓ APPROVE
-  Performance: ✓ APPROVE
-  Architecture: ✓ APPROVE
-  UX: ✓ APPROVE
+### 4.4 Conflicts & Uncertainties
+```markdown
+## Conflicts & Uncertainties
 
-Running verification...
-  ✓ typecheck passed
-  ✓ lint passed
+### Conflict 1: [Description]
+- Expert A says: [X]
+- Expert B says: [Y]
+- Resolution: [Higher confidence wins / Needs human review]
 
-All checks passed! ✅
+### Uncertain Findings (require manual verification)
+- [Finding with confidence = MEDIUM and status = uncertain]
 ```
 
 ---
 
-## When to Use
+## PHASE 5: POST-REVIEW ACTIONS
 
-✅ **Use /experts for:**
-- Critical changes (auth, payments, schema)
-- Before submitting PRs
-- Large refactors
-- Learning (get feedback)
+### 5.1 If APPROVED
+```
+EXECUTE:
+1. Run typecheck: npm run typecheck
+2. Run lint: npm run lint
+3. Report any new errors
+4. IF all pass → "Ready for commit"
+5. IF any fail → Document failures, do NOT change decision
+```
 
-❌ **Don't use for:**
-- WIP code
-- Trivial changes (typos)
-- Generated code
+### 5.2 If REJECTED
+```
+OUTPUT:
+1. List all blocking issues with fixes
+2. Prioritize by: confidence DESC, severity DESC
+3. Provide actionable next steps
+4. Memory Expert logs patterns for future prevention
+```
+
+### 5.3 Memory Expert Handoff
+```
+ALWAYS:
+- Pass all findings to Memory Expert
+- Memory Expert checks for patterns (>= 3 occurrences)
+- If threshold met, propose auto-improvement
+- Log decision in cloud database
+```
 
 ---
 
-## Advanced Options
+## QUICK REFERENCE
+
+### Confidence Levels
+| Level | Meaning | Can Block? |
+|-------|---------|------------|
+| CERTAIN | Direct evidence, verified | YES |
+| HIGH | Pattern + context verified | YES |
+| MEDIUM | Pattern match, gaps exist | Only if CRITICAL severity |
+| LOW | Inference only | NO |
+
+### Severity Levels
+| Level | Examples |
+|-------|----------|
+| CRITICAL | SQL injection, auth bypass, data loss |
+| HIGH | N+1 queries, missing validation, type unsafety |
+| MEDIUM | Code smells, minor performance, missing a11y |
+| LOW | Style issues, minor improvements |
+
+### Expert Quick Guide
+| Expert | Domain | Blocks On |
+|--------|--------|-----------|
+| Security | SQL, auth, XSS, validation | Any HIGH+ security issue |
+| Performance | N+1, waterfalls, bundle | Quantified impact > threshold |
+| Architecture | Types, modules, SOLID | Type violations, circulars |
+| UX | A11y, mobile, tokens | WCAG violations |
+| Database | Schema, migrations | Data loss risk |
+| Memory | Patterns | Never (ABSTAIN only) |
+| Documentation | Docs accuracy | Never (ABSTAIN only) |
 
-```bash
-# Review specific experts only
-/experts src/file.ts --only security,architecture
+---
 
-# Verbose output (show reasoning)
-/experts src/file.ts --verbose
+## ANTI-PATTERNS TO AVOID
 
-# Dry run (no auto-improvements)
-/experts src/file.ts --dry-run
-```
+| Wrong | Right |
+|-------|-------|
+| "Looks good" | "Reviewed X files, Y patterns checked, Z findings with confidence levels" |
+| "Security approved" | "Security: No SQL injection (searched 5 patterns), auth middleware verified on 3 routes" |
+| "REJECTED" | "REJECTED: N+1 at file.ts:45 (confidence: CERTAIN, impact: 50 queries/page)" |
+| Skip pre-analysis | ALWAYS run Phase 1 before invoking experts |
+| Ignore ABSTAIN | Document why expert abstained for transparency |
 
 ---
 
-*Part of cmp-memory-system - MetaNautical Group*
+*Expert Review System v2.0 - Evidence-Based Code Analysis*