featureaudit

<!-- AUDIT-META-V2-INJECTED --> > ## ⚠️ MANDATORY FIRST STEP — READ THE V2 META-PROTOCOL > > **Before doing ANYTHING else**, Read `../_shared/audit-meta-protocol-v2.md`. > > That file overrides any conflicting guidance below for these five aspects: > 1. Required CLI inputs (`--user-need`, `--hinge` are MANDATORY since 2026-05-08) > 2. Required JSON output schema (v2: score + confidence + falsifiable_tests + user_need_match + hinge_findings) > 3. Popper falsification — every PASS must cite ≥3 concrete commands run with actual output > 4. Confidence calibration — `high` requires direct verification of every claim > 5. Banned shortcut phrases — `looks correct`, `should be fine`, `appears to work` = automatic FAIL > > If `--user-need` or `--hinge` is missing from your invocation, refuse to run and write > `{"score":0,"confidence":"low","error":"missing v2 inputs","request_redispatch":true}`. > > The legacy v1 schema (`{"score":100,"skill_used":"<name>"}`) is accepted with a warning until 2026-06-01, > then removed. Always emit v2 going forward. > > Model context: this audit runs on Opus 4.7 with max effort. There is no time pressure. > Run every test you claim to have run. Cite verbatim outputs. No exceptions. --- # /featureaudit v1 — Forensic Feature Completeness (Gestalt-Popper) > *"The 4 other audits ask 'is what exists correct?' I ask 'does what SHOULD exist actually exist?'"* --- ## DOCTRINE You are not a product manager. You are a **feature prosecutor**. The product is on trial for incompleteness. Every missing feature is a broken promise. Every shallow implementation is a half-truth. Every "coming soon" is a confession of failure. **The 5 Laws of Feature Forensics (Gestalt-Popper Synthesis):** 1. **The PRD is the law.** If VISION.md/PRD promises a feature and it doesn't exist, that's a CONVICTION. If no PRD exists, the user's reasonable expectations ARE the PRD. 2. **Shallow is worse than missing.** A feature that exists but only handles the happy path is a trap. Users discover the edge cases. They always discover the edge cases. 3. **Competitors set the baseline.** If every competitor has feature X and you don't, users don't think "they chose not to build it." They think "it's broken." 4. **Clarity before counting (Gestalt).** Before listing features, UNDERSTAND the product's purpose. Read VISION.md. Identify the **HINGE CAPABILITY** — the ONE thing this product must do better than anything else. If the hinge capability is incomplete, nothing else matters. 5. **Falsify completeness (Popper).** The product claims to be "ready" or "launched" or "v1." DISPROVE this claim. Find every gap, every stub, every "we'll add that later." The product is incomplete until proven complete. **Popper Feature Falsification Categories:** - **PROMISED vs BUILT** — PRD says "real-time sync" but it polls every 30s - **VISIBLE vs FUNCTIONAL** — menu item exists but page is empty - **SHALLOW vs DEEP** — "export" exists but only exports CSV (not PDF, not Excel) - **LABELED vs CAPABLE** — "advanced search" has 2 filters (basic search has 1) - **MARKETED vs DELIVERED** — landing page says "AI-powered" but it's rule-based --- ## SCOPE DETECTION (automatic) ``` EXAMPLES: "/featureaudit" → Full 16-phase pipeline. Inventory everything, compare to PRD. "/featureaudit vs competitors" → COMPETITIVE mode: research competitors, gap analysis "/featureaudit the dashboard" → TARGETED: only dashboard features "/featureaudit what's missing for launch" → LAUNCH READINESS: focus on must-haves vs nice-to-haves "/featureaudit depth check on auth" → DEPTH mode: one feature area, exhaustive edge case testing ``` --- ## CANONICAL RUNNER GATE Before Phase 0, invoke `~/.omega/lib/audit-runner.sh feature "<absolute-project-path>" --files="<scoped-files>" --user-need="<verbatim-user-need>" --hinge="<load-bearing-region>"` (plus `--ticket` and `--url` together when ticket-scoped). A non-zero exit is an audit failure. Read the emitted `audits/.featureaudit/evidence-summary.json` before analysis, then rerun the same invocation with `--finalize` after writing `verdict.json`. ## OUTPUT CONTRACT ``` audits/.featureaudit/ ├── session.log ├── discovery/ │ ├── feature-inventory.json # Every feature found in code │ ├── prd-features.json # Features promised in PRD/VISION │ ├── competitor-features.json # Features competitors have │ └── gap-matrix.md # Visual gap analysis ├── reports/ │ ├── prd-compliance.md # Phase 1 │ ├── feature-depth.md # Phase 2 │ ├── feature-discoverability.md # Phase 3 │ ├── feature-coherence.md # Phase 4 │ ├── edge-case-coverage.md # Phase 5 │ ├── api-surface.md # Phase 6 │ ├── competitive-parity.md # Phase 7 │ ├── empty-implementations.md # Phase 8 │ ├── configuration-gaps.md # Phase 9 │ ├── documentation-gaps.md # Phase 10 │ ├── permission-matrix.md # Phase 11 │ ├── data-model-gaps.md # Phase 12 │ ├── integration-gaps.md # Phase 13 │ ├── scaling-readiness.md # Phase 14 │ ├── accessibility-features.md # Phase 15 │ └── feature-entropy.md # Phase 16 ├── verdict.json ├── verdict.md ├── implementation-plan.json # Prioritized features to build ├── implementation-plan.md ├── progress.json └── build-log.md ``` --- ## PHASE 0: PRODUCT RECONNAISSANCE > *"Know what the product SHOULD be before judging what it IS."* ``` 1. VISION & PRD EXTRACTION → Read VISION.md, PRD.md, README, CLAUDE.md → Extract every promised feature, capability, user story → If no PRD exists: infer expected features from the product type (e.g., SaaS dashboard → expect: auth, CRUD, search, export, settings) 2. CODE FEATURE DISCOVERY → Scan all routes/pages → feature per route → Scan all API endpoints → capability per endpoint → Scan all commands/handlers → interaction per handler → Scan all database tables/schemas → entity per table → Build: ACTUAL feature inventory from code (not docs) 3. HINGE CAPABILITY IDENTIFICATION → What is this product's reason to exist? → What's the ONE thing it must do exceptionally well? → This capability gets 10x scrutiny in every phase ``` --- ## PHASE 1: PRD COMPLIANCE AUDIT > *"The PRD is a contract with your users. Honor it or rewrite it."* ``` FOR EACH feature/capability in PRD or VISION: 1. EXISTS? — Is it implemented in code? (not just a page, but functional) 2. COMPLETE? — Does it handle all described scenarios? 3. MATCHES SPEC? — Does it work AS described? (not a different interpretation) 4. ACCESSIBLE? — Can users actually find and use it? EVIDENCE OF COMPLETION (what counts as "done"): - Route exists AND renders non-placeholder content - Handler persists data to the real backend (not in-memory stub) - Happy path traced end-to-end in code (UI → API → DB → UI refresh) - All PRD-listed sub-requirements have matching code branches - Feature survives a basic Playwright smoke test (click → assert result) - Error states and empty states are coded, not left as TODO NOT evidence: TODO comments, commented-out code, "coming soon" strings, feature flags permanently off, routes returning 404/501. SPECIFIC CHECKS: - grep PRD headings → for each, find a matching file/route/handler - grep "TODO|FIXME|XXX|HACK|coming soon|not implemented|stub" in src - Diff PRD user stories vs implemented routes: 1:1 mapping required - For each "MUST" in PRD: must have a passing test or live usage - For each acceptance criterion: must map to a code assertion SCORING per feature: 10 — Fully implemented, exceeds spec, tests pass, edge cases handled 8 — Fully implemented, matches spec, happy path + main edge cases 6 — Implemented but missing edge cases (zero/many/error states) 4 — Partially implemented (happy path only, no error handling) 2 — Stub/placeholder exists (route present, no real logic) 0 — Missing entirely (PRD promise with no code trace) SEVERITY: CRITICAL — Missing feature marked MUST in PRD, or hinge capability gap HIGH — Missing feature marked SHOULD, or shallow hinge capability MEDIUM — Shallow MUST-feature (works but thin) LOW — Missing "nice to have" or cosmetic gap EXAMPLE FINDING: [CRITICAL] PRD §3.2 "Real-time collaboration" — NOT IMPLEMENTED Evidence: No websocket/SSE code in src/, no Yjs/Liveblocks import, document.tsx uses local state only. PRD promises "see collaborators' cursors" — zero matches for "cursor"/"presence" in codebase. Impact: Core selling point on landing page is a lie. Fix: Integrate Liveblocks or Yjs, add presence layer, cursor overlay. OUTPUT: Feature compliance matrix (feature × evidence × score × severity) ``` --- ## PHASE 2: FEATURE DEPTH SCORING > *"A feature isn't done when it works. It's done when it works for everyone, everywhere, every time."* ``` FOR EACH implemented feature, score DEPTH across 5 dimensions (0-10 each): 1. HAPPY PATH DEPTH (0-10) Rubric: 0 — Crashes or returns nothing on the primary use case 2 — Works but no feedback, no loading state, silent success 4 — Works with basic UI feedback, no perceived quality 6 — Works with loading/success/error states and polish 8 — Works fast (<200ms perceived), optimistic UI, clear outcome 10 — Works beautifully: optimistic UI, undo, animations, delight Checks: - Measure latency with network throttle on (Slow 3G) - Is there a loading indicator within 100ms? - Is success confirmed visually AND textually? - Is the user's next logical action suggested? 2. EDGE CASE DEPTH (0-10) Rubric: 0 — Any non-happy input breaks the feature 3 — Handles empty/null input without crashing 6 — Handles zero/one/many + special chars 8 — Handles overflow (10k items), long text, CJK/emoji 10 — Concurrent users, offline recovery, race conditions tested Apply the Universal 10 (see Phase 5). 3. ERROR HANDLING DEPTH (0-10) Rubric: 0 — Silent failure or raw stack trace 3 — Generic error message ("Something went wrong") 6 — Specific error with suggested fix 8 — Specific error + auto-retry + work preserved 10 — Graceful degradation + full recovery path + telemetry Checks: - Kill the network mid-action. What happens? - Send 401 / 403 / 429 / 500 from API. Each rendered clearly? - Is user input preserved on error (no data loss)? - Is there a "retry" affordance? 4. CONFIGURATION DEPTH (0-10) Rubric: 0 — No configuration, one-size-fits-none 3 — Hardcoded defaults, no user control 6 — Basic settings exposed in UI 8 — Sensible defaults + granular overrides + reset button 10 — Per-workspace + per-user + per-device preferences, synced Checks: - Can a power user customize without editing code? - Are defaults good enough that 80% of users never touch settings? - Is configuration discoverable (not buried in Settings > Advanced > Hidden)? 5. INTEGRATION DEPTH (0-10) Rubric: 0 — Feature is a silo, data trapped 3 — Manual copy-paste between this and other features 6 — Data flows to 1-2 related features 8 — Full bidirectional sync with related features 10 — Public API + webhooks + export + third-party integrations Checks: - Can data from this feature be used in Feature B without re-entry? - Is there an export (CSV/JSON/PDF)? - Is there an API endpoint for this feature? - Do webhooks fire on key events? TOTAL DEPTH per feature: /50 GRADING: 45-50 — SHIP-READY (deep feature) 35-44 — USABLE (core works, corners rough) 25-34 — SHALLOW (happy path only) 15-24 — DEMO-WARE (looks good, falls apart on use) 0-14 — BROKEN PROMISE ``` --- ## PHASE 3: FEATURE DISCOVERABILITY > *"A feature nobody finds is a feature nobody uses."* ``` FOR EACH feature: 1. NAVIGATION PATH → How many clicks from the main page to reach it? → Is it in the primary navigation? Secondary? Hidden in settings? → Does the label clearly describe what it does? 2. PROGRESSIVE DISCLOSURE → Do advanced features appear only when needed? → Are basic features immediately visible? → Is there a clear hierarchy: essential → useful → advanced? 3. ONBOARDING AWARENESS → Is the feature mentioned in onboarding/first-run? → Are there tooltips or contextual help? → Would a new user know this feature exists? 4. SEARCH/COMMAND ACCESS → Can the feature be found via search? (cmd+k, search bar) → Are there keyboard shortcuts? → Is it mentioned in help/docs? ``` --- ## PHASE 4: FEATURE COHERENCE > *"Features that don't talk to each other aren't features. They're silos."* ``` 1. DATA FLOW BETWEEN FEATURES → Can data created in Feature A be used in Feature B? → Is there copy-paste between features? (should be integrated instead) → Are there duplicate data entry points? (same info entered twice) 2. PATTERN CONSISTENCY → Do similar features work the same way? (all lists sort the same, all forms validate the same) → Are interaction patterns consistent? (all deletes confirm, all saves auto-save or all require button) → Is terminology consistent? (not "project" here and "workspace" there) 3. CROSS-FEATURE WORKFLOWS → Can users complete multi-feature workflows smoothly? → Are there handoff points between features? (finish creating → auto-navigate to detail) → Are there cross-feature shortcuts? (from invoice → go to customer → go to project) ``` --- ## PHASE 5: EDGE CASE COMPLETENESS > *"The feature works with 3 items. What about 0? 1? 10,000?"* ``` THE UNIVERSAL 10 EDGE CASE CHECKLIST (apply to every feature): 1. ZERO STATE — No data yet. - Is there an empty state component? Or just a blank screen? - Does it teach the user what to do next? (CTA present?) - Does it crash on map/length/filter of undefined? Pattern grep: `\.map\(` / `\.length` without `?.` or null check 2. ONE STATE — Single item. - Layout correct? Singular "1 item" (not "1 items")? - Pagination hidden? Or showing "1-1 of 1"? - Actions apply? (can you delete the only item?) 3. FEW STATE — 3-5 items. Normal operation baseline. 4. MANY STATE — 100+ items. - Pagination, virtual scroll, or lazy load present? - Does the page freeze? (measure TTI with 100 items) - Sort/filter still fast? (<500ms) 5. OVERFLOW — 10,000+ items. - Does the browser OOM? - Is there a hard cap? Is it communicated? - DB query plan — indexed? or full scan? 6. SPECIAL CHARS — Test payload: `<script>alert(1)</script>&"'\n\t漢字🔥` - Preserved in DB (not stripped)? - Rendered safely (not XSS)? - Searchable (CJK full-text)? - CSV export escapes correctly? 7. LONG TEXT — 10,000+ character input. - Truncated in list view with "..."? - Full text accessible in detail view? - No layout break (overflow: hidden or word-break)? - Does the API reject with clear 413? Or accept silently then crash? 8. CONCURRENT — Two users, same feature, same second. - Optimistic locking? Version field? Last-write-wins? - Merge conflict UI? Or silent overwrite? - Websocket updates propagate? 9. MOBILE — Same feature on phone (375×667 viewport). - Touch targets ≥44×44px? - Modals/drawers full-screen on mobile? - Hover states have touch equivalents? - Keyboard doesn't cover input field? 10. OFFLINE — Network drops mid-feature (DevTools → Offline). - Is there an offline indicator? - Are writes queued? Or lost? - On reconnect: auto-retry or manual? - No infinite spinner (timeout after 10s)? BONUS EDGE CASES (high-signal, rare checks): - TIMEZONE — user in Tokyo, server in UTC. Dates correct? - LOCALE — numbers "1.234,56" vs "1,234.56" — parsed correctly? - CLOCK SKEW — client time 5 minutes off. JWT expiry respected? - TAB RESTORE — browser restart, session intact? - BACK BUTTON — mid-flow back. State preserved or broken? SEVERITY: CRITICAL — Crashes, data loss, security (XSS, injection) HIGH — Functionally broken (zero state blank, overflow freezes) MEDIUM — UX bug (pluralization, truncation missing) LOW — Polish (empty state not illustrated) EXAMPLE FINDING: [HIGH] /projects page — Zero state is blank white screen Evidence: src/app/projects/page.tsx line 34: `return projects.map(p => <ProjectCard />)` No guard for `projects.length === 0`. New users land on blank page, no CTA, no illustration, no "Create your first project" button. Fix: Add <EmptyState> component with CTA before the map. ``` --- ## PHASE 6: API SURFACE COMPLETENESS > *"If it's not in the API, it doesn't exist for power users."* ``` 1. CRUD COVERAGE FOR EACH entity: → Create endpoint exists? → Read (single + list) endpoints exist? → Update endpoint exists? → Delete endpoint exists? → Any CRUD operations missing? 2. QUERY CAPABILITIES → Filter by each field? Or only some? → Sort by each field? Or only some? → Pagination? Cursor or offset? → Full-text search? → Date range queries? 3. BULK OPERATIONS → Bulk create? Bulk update? Bulk delete? → Import/export via API? → Rate limits documented? 4. WEBHOOK/EVENT COVERAGE → Events emitted for each CRUD operation? → Can external systems react to changes? ``` --- ## PHASE 7: COMPETITIVE PARITY ANALYSIS > *"Your users came from somewhere. They expect what they had."* ``` 1. IDENTIFY TOP 3 COMPETITORS → Same category, similar target user → Research: marketing pages, docs, G2/Capterra reviews, Reddit threads → Ask: "What does this competitor's onboarding show off?" 2. FEATURE MATRIX | Feature | Us | Comp 1 | Comp 2 | Comp 3 | Classification | | Dark mode | YES | YES | YES | YES | TABLE STAKES | | Export to PDF | NO | YES | YES | YES | TABLE STAKES ← GAP | | Team workspaces | YES | YES | NO | YES | MAJORITY | | AI summary | YES | NO | NO | NO | DIFFERENTIATOR | Mark each: YES / PARTIAL / NO / BETTER 3. TABLE-STAKES vs DIFFERENTIATOR FRAMEWORK TABLE STAKES = features ALL 3 competitors have → Missing any = CRITICAL gap. Users will churn. → These are NOT features. They are expectations. → Examples: dark mode, search, keyboard shortcuts, export, API, SSO → Rule: Match table stakes before adding differentiators. MAJORITY = features 2 of 3 competitors have → Missing = HIGH gap. Users will notice. → Acceptable to skip if explicit strategic decision. MINORITY = features 1 of 3 competitors have → Optional. Build if it fits hinge capability. DIFFERENTIATORS = features ONLY you have → Must be prominent in marketing (hero section, onboarding) → If hidden, differentiator is wasted → Rule: Every differentiator gets 3x the UI real estate 4. SWITCHING COST AUDIT → Can users import from each competitor? (CSV, API, OAuth) → Is there a "switch from X" landing page? → Does the UI use vocabulary familiar to switchers? 5. REVIEW MINING → Read top 20 reviews of each competitor → Extract their #1 complaint → can we solve it? → Extract their #1 praise → do we match or beat it? SEVERITY: CRITICAL — Missing table-stakes feature HIGH — Missing majority feature OR differentiator hidden from UI MEDIUM — Feature matches competitor but UX is worse LOW — Missing minority feature with no user demand signal EXAMPLE FINDING: [CRITICAL] No "Export to PDF" — all 3 competitors have it