Add domain probes, stub detection, and symptom triage

commands/feature.md

@@ -8,6 +8,8 @@ Complete feature lifecycle: brainstorm → plan → implement → test → lint
 
 ## Step 1: Brainstorm
 
+Identify the feature's relevant domains (auth, API, database, UI, etc. — features often span multiple) and read each matching section from `references/domain-probes.md` to surface gray areas. If no section matches, skip domain probing. Use the probes to ask targeted questions via `AskUserQuestion` — only for genuinely ambiguous decisions, not obvious ones. Skip probing if the user's input already resolves the gray areas.
+
 ```
 Feature: {user's input}
 
@@ -16,8 +18,9 @@ Think through the design:
 - What's the simplest approach that works?
 - What are the risks or unknowns?
 - Are there edge cases to handle upfront?
+- What gray areas need user input before planning? (use domain probes)
 
-Produce a short design summary. Don't write code yet.
+Produce a short design summary with decisions locked. Don't write code yet.
 ```
 
 ## Step 2: Plan

commands/references/debug-checklists.md

@@ -2,6 +2,22 @@
 
 Domain-specific checklists for inclusion in debug agent prompts. Include only the relevant checklist based on the identified bug domain.
 
+## Symptom Triage
+
+When the bug domain isn't obvious, use the symptom to route to the right checklist:
+
+| Symptom | Check first |
+|---------|------------|
+| "Cannot read property of undefined/null" | API Bugs (response shape), Auth Bugs (missing token) |
+| "X is not a function" | API Bugs (import/module), Async Bugs (missing await) |
+| Works sometimes, fails sometimes | Async/Concurrency Bugs |
+| Works locally, fails in CI/prod | Auth Bugs (env config), Database Bugs (schema drift) |
+| Wrong data displayed | Database Bugs (stale data), API Bugs (query params) |
+| Timeout or hang | Database Bugs (pool exhaustion), Performance Bugs |
+| Memory leak / growing resource usage | Async Bugs (listener leak), Performance Bugs |
+| 401/403 after deploy | Auth Bugs (token/session mismatch) |
+| Slow response | Performance Bugs |
+
 ## API Bugs
 - Does the route exist and match the HTTP method?
 - Is auth middleware applied and in the correct order?
@@ -30,15 +46,8 @@ Domain-specific checklists for inclusion in debug agent prompts. Include only th
 
 ## Performance Bugs
 - Profile first — the slow part is almost never where you think
-- Check for N+1 queries, missing indexes, unbounded loops
-- Memory leak? Compare heap snapshots over time
-- Connection pool or thread pool exhaustion?
-
-### Quick Symptom Lookup
-
-| Symptom | Likely Cause | Investigation |
-|---------|--------------|---------------|
-| Slow API response | N+1 queries | Log SQL count per request |
-| Slow page render | Expensive recomputation | Profile render cycle |
-| Gradual memory growth | Leak (listeners, connections) | Heap snapshots over time |
-| Intermittent slowness | Lock contention / pool exhaustion | Connection pool metrics |
+- Slow API response? Log SQL count per request — likely N+1 queries
+- Slow page render? Profile the render cycle — likely expensive recomputation
+- Gradual memory growth? Heap snapshots over time — likely leaked listeners or connections
+- Intermittent slowness? Check connection pool metrics — likely lock contention or pool exhaustion
+- Check for missing indexes and unbounded loops

commands/references/domain-probes.md

@@ -0,0 +1,79 @@
+# Domain-Aware Probing Patterns
+
+When brainstorming a feature, identify its domain and use the matching probes to surface gray areas before planning. Load only the relevant domain — not the full file.
+
+## Authentication
+
+| User mentions | Probe |
+|---|---|
+| "login" / "auth" | OAuth, email/password, magic link, or SSO? |
+| "sign up" | Required fields? Email verification? |
+| "MFA" / "2FA" | TOTP, SMS, or passkey? Recovery flow? |
+| "session" | Duration? Refresh strategy? Multi-device? |
+| "roles" / "permissions" | RBAC, ABAC, or simple admin/user? Granularity? |
+
+## Real-Time / WebSockets
+
+| User mentions | Probe |
+|---|---|
+| "real-time" / "live" | WebSocket, SSE, or polling? Acceptable latency? |
+| "notifications" | In-app, push, email, or all three? Batching? |
+| "collaboration" | Conflict resolution strategy? Presence indicators? |
+| "chat" / "messaging" | Message persistence? Read receipts? Typing indicators? |
+
+## Dashboard / Data Display
+
+| User mentions | Probe |
+|---|---|
+| "dashboard" | Data sources? How many distinct views? |
+| "charts" / "graphs" | Interactive or static? Drill-down? Export? |
+| "metrics" / "KPIs" | Refresh — real-time, polling, or on-demand? Acceptable staleness? |
+| "admin panel" | Role-based visibility? Actions beyond viewing? |
+| "table" / "list" | Pagination, infinite scroll, or load-all? Sorting? Filtering? |
+
+## API Design
+
+| User mentions | Probe |
+|---|---|
+| "API" / "endpoints" | REST, GraphQL, or RPC? Versioning strategy? |
+| "pagination" | Cursor, offset, or keyset? Default page size? |
+| "rate limiting" | Per-user, per-key, or global? Limits? |
+| "webhooks" | Retry policy? Signature verification? |
+| "file upload" | Max size? Allowed types? Direct-to-storage or through API? |
+
+## Database / Storage
+
+| User mentions | Probe |
+|---|---|
+| "database" | SQL or NoSQL? Why? Expected scale? |
+| "migration" | Zero-downtime required? Rollback strategy? |
+| "caching" | What layer? TTL? Invalidation strategy? |
+| "search" | Full-text, fuzzy, or exact? Dedicated search engine? |
+| "file storage" | Local, S3, or CDN? Access control? |
+
+## UI / Frontend
+
+| User mentions | Probe |
+|---|---|
+| "form" | Validation — client, server, or both? Multi-step? |
+| "mobile" | Responsive web, native, or PWA? Offline support? |
+| "dark mode" / "theme" | System preference, user toggle, or both? |
+| "loading" / "skeleton" | Skeleton screens, spinners, or progressive? |
+| "empty state" | What shows when there's no data? CTA? |
+
+## Testing
+
+| User mentions | Probe |
+|---|---|
+| "tests" | Unit, integration, e2e, or all? Coverage target? |
+| "CI" | Which provider? Required checks before merge? |
+| "staging" | Separate environment? Data strategy (seed, copy, synthetic)? |
+
+## Deployment
+
+| User mentions | Probe |
+|---|---|
+| "deploy" | Manual, CI/CD, or GitOps? Rollback strategy? |
+| "environment" | How many? (dev, staging, prod) Config management? |
+| "Docker" / "container" | Orchestration? Health checks? Resource limits? |
+| "serverless" | Cold start acceptable? Timeout limits? |

commands/references/stub-patterns.md

@@ -0,0 +1,67 @@
+# Stub & Placeholder Detection Patterns
+
+Mechanical grep patterns for detecting unfinished work. Use in self-audit's Stale Code section or tri-review to flag incomplete implementations.
+
+All matches require manual review — these are heuristics, not definitive indicators.
+
+## TODO/FIXME Comments
+
+```bash
+grep -rn 'TODO\|FIXME\|HACK\|XXX\|PLACEHOLDER' \
+  --include='*.go' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' \
+  --include='*.py' --include='*.rs' --include='*.rb' . 2>/dev/null
+```
+
+## Empty or Trivial Implementations
+
+```bash
+# Functions that return nothing useful — high false-positive rate.
+# Filter results manually: these returns are often legitimate.
+# Strongest signal when combined with TODO/FIXME nearby.
+grep -rn 'return nil' --include='*.go' . 2>/dev/null
+grep -rn 'return null\|return undefined' --include='*.ts' --include='*.js' . 2>/dev/null
+grep -rn 'return None' --include='*.py' . 2>/dev/null
+
+# Python pass-only functions (indented pass on its own line)
+grep -rEn '^[[:space:]]+pass[[:space:]]*$' --include='*.py' . 2>/dev/null
+
+# Empty catch/error blocks (use grep -E for extended regex portability)
+grep -rEn 'catch[^{]*\{\s*\}' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' . 2>/dev/null
+```
+
+## Placeholder Text
+
+```bash
+# UI placeholders left in
+grep -rni 'lorem ipsum\|coming soon\|under construction\|placeholder' \
+  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' \
+  --include='*.html' --include='*.vue' --include='*.svelte' . 2>/dev/null
+
+# Template brackets left in
+grep -rn '\[TODO\]\|<TODO>\|{TODO}' \
+  --include='*.md' --include='*.ts' --include='*.tsx' --include='*.go' . 2>/dev/null
+```
+
+## Hardcoded Values Where Dynamic Expected
+
+```bash
+# Hardcoded IDs or secrets (not in test files)
+grep -rn 'api_key\s*=\s*"[^"]\+"\|password\s*=\s*"[^"]\+"' \
+  --include='*.go' --include='*.ts' --include='*.tsx' --include='*.py' . 2>/dev/null | grep -v '_test\.\|\.test\.\|\.spec\.\|test_'
+
+# Hardcoded URLs (not config/const files)
+grep -rn 'http://localhost\|127\.0\.0\.1' \
+  --include='*.go' --include='*.ts' --include='*.tsx' --include='*.py' . 2>/dev/null | grep -v 'config\|const\|test\|spec'
+```
+
+## Disabled or Skipped Tests
+
+```bash
+# Skipped tests
+grep -rn '\.Skip\|t\.Skip\|xit(\|xdescribe(\|@pytest\.mark\.skip\|@unittest\.skip' \
+  --include='*.go' --include='*.ts' --include='*.js' --include='*.py' . 2>/dev/null
+
+# Commented-out test blocks
+grep -rn '// func Test\|// it(\|// test(\|# def test_' \
+  --include='*.go' --include='*.ts' --include='*.js' --include='*.py' . 2>/dev/null
+```

commands/self-audit.md

@@ -75,9 +75,8 @@ Record: total coverage %, lowest-coverage packages, untested files.
 # Python: pip-audit or safety check
 # Rust: cargo audit
 
-# Hardcoded secrets
-grep -rn 'password\s*=\s*"[^"]*"' --include='*.go' --include='*.ts' --include='*.py' . 2>/dev/null | head -5
-grep -rn 'api_key\s*=\s*"[^"]*"' --include='*.go' --include='*.ts' --include='*.py' . 2>/dev/null | head -5
+# Hardcoded secrets — use the patterns from references/stub-patterns.md
+# "Hardcoded Values Where Dynamic Expected" section (excludes test files, includes .tsx)
 ```
 
 ### Stale Code
@@ -87,10 +86,14 @@ grep -rn 'api_key\s*=\s*"[^"]*"' --include='*.go' --include='*.ts' --include='*.
 # Unused dependencies
 # go mod tidy -diff (shows removable deps)
 # npm prune --dry-run
-# TODO/FIXME/HACK count
-grep -rn 'TODO\|FIXME\|HACK\|XXX' --include='*.go' --include='*.ts' --include='*.py' --include='*.rs' . 2>/dev/null | wc -l
+# TODO/FIXME/HACK count — matches stub-patterns.md canonical list
+grep -rn 'TODO\|FIXME\|HACK\|XXX\|PLACEHOLDER' \
+  --include='*.go' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' \
+  --include='*.py' --include='*.rs' --include='*.rb' . 2>/dev/null | wc -l
 ```
 
+For deeper stub detection (empty implementations, placeholder text, hardcoded values, skipped tests), run the patterns from `references/stub-patterns.md`. Run unconditionally — a repo can have zero TODOs but still contain empty catch blocks, placeholder UI copy, or hardcoded localhost URLs.
+
 ### Documentation
 
 ```bash