# v2 Analysis — Self-Challenge & Reframing **Date**: 2026-03-31 --- ## The Challenge v2 identified 7 issue clusters and proposed a 3-phase point-fix plan. This document challenges whether we found the REAL core problems, the REAL bottleneck, and what needs SYSTEMIC solutions. --- ## Challenge 1: Layout is NOT the #1 Problem ### v2 Claim "Layout dead code is the #1 blocker (32+ issues)" ### Counter-Evidence 181 open issues break down as: | Category | Count | Nature | |----------|-------|--------| | Missing features / not implemented | 66 | **Can't use at all** | | Rendering / display / layout | 65 | Looks wrong but might function | | Testing / CI broken on main | 40 | Dev velocity blocker | | Data / metadata quality | 27 | Cascading quality issues | **66 "missing" issues > 32 layout issues.** And "missing" means users literally cannot complete workflows — Activity tab, Lead conversion, Approval Actions, Record Type selection. These are **functional blockers**, not cosmetic. ### Reframed Core Problem The core problem is NOT "layouts are wrong." The core problem is: > **No standard object has a complete end-to-end workflow.** Layout is one symptom. Others include: - Activity tab missing from Opportunity/Contact (P0) — engagement tracking impossible - Lead conversion sends wrong request format (P0) — sales pipeline broken - Approval wizard has no Actions configuration — approval workflow incomplete - Quote creation blocked by Record Type "Next" button — Quote CPQ impossible - Error feedback missing on ALL 400 responses — users see no feedback on failures Fixing layout makes pages LOOK right. But a page with perfect layout and no Activity tab is still unusable. --- ## Challenge 2: The Bottleneck is Not Technical — It's the Absence of Object Completeness Definition ### v2 Claim "Phase 1-3 point fixes will close ~96 issues" ### Counter-Evidence After Phase 1-3, what prevents the SAME patterns from recurring? - Next object added → no seed layout → same 32 issues - Next field discovered → no label → same 18 issues - Next validation rule → references missing field → same crash - Next workflow built → no contract test → same silent failures The point fixes treat each occurrence. **Nothing prevents recurrence.** ### The Real Bottleneck **There is no definition of "done" for an object.** No checklist, no automated validation, no contract that says "Account is complete when X, Y, Z all pass." Currently: ``` Developer builds feature → Manual testing → Someone finds gap → Issue filed → Fix → Repeat ``` Should be: ``` Object completeness contract defined → Automated check at bootstrap/CI → Gaps flagged before manual testing ``` ### What an Object Completeness Contract Would Look Like For each standard object (Account, Contact, Opportunity, Lead, Campaign, Quote, Order, Contract, Case): 1. **Schema completeness**: All Salesforce-reference fields exist in `_System_Field` with correct types, labels, and required flags 2. **Layout completeness**: At least one non-auto-generated `_System_PageLayout` exists with `IsCustomized=1`, containing named sections (not just "Additional Details") 3. **Validation rules**: All rules reference only existing fields (no broken formula references) 4. **Picklist values**: All picklist fields have at least one value defined, default values set where Salesforce has them 5. **Record types**: If Salesforce has record types, `_System_RecordType` has matching entries 6. **Related lists**: Business-relevant related lists configured (not just auto-discovered) 7. **Workflow integration**: Required tabs exist (Activity, Related, Details), required actions exist (Edit, Delete, Clone, object-specific actions) 8. **API contract**: `GET /sobjects/{Object}/describe` response matches Salesforce structure (field count within 10%, all required fields present) **This is the systemic fix.** Not loading a JSON file — building a validation framework that catches gaps before they become 221 issues. --- ## Challenge 3: Three Systemic Deficits (Reframing the 7 Clusters) The 7 clusters in v2 are symptoms of THREE systemic deficits: ### Deficit A: No Metadata Quality Gate (drives ~70 issues) **Symptoms**: Layout cluster (32), Label cluster (18), Related list cluster (6), validation rule crashes, picklist missing values, field type mismatches **Root cause**: Bootstrap runs DDL + data seeding with no validation step. Fields are created without verifying labels, types, and constraints match the Salesforce reference. Layouts auto-generated without verifying section structure matches. **Systemic fix**: Add a `ValidateMetadataQuality()` step to bootstrap that: - Checks every `_System_Field` has a non-empty, non-API-name Label - Checks every standard object has a non-auto-generated layout - Checks every validation rule's formula references only existing fields - Checks every picklist field has at least one value - Logs warnings for gaps, optionally fails startup in strict mode **Files**: New `backend/internal/bootstrap/metadata_validator.go` ### Deficit B: No End-to-End Workflow Verification (drives ~50 issues) **Symptoms**: Missing Activity tab, broken Lead conversion, incomplete Approval wizard, Quote creation blocked, no error feedback on 400s, missing Clone/Upload actions **Root cause**: Features are built bottom-up (backend API → frontend component) without top-down verification ("can a user complete the standard Salesforce workflow for this object?"). No E2E test or contract test validates the complete user journey. **Systemic fix**: Define object workflow contracts — for each standard object, a checklist of operations that must work: - Create (with Record Type selection if applicable) - Edit (with layout, field validation, error feedback) - Detail view (with correct layout sections, highlights, related lists, tabs) - List view (with filtering, sorting, column customization, row navigation) - Object-specific actions (Lead: Convert; Quote: Create from Opportunity; Approval: Submit/Approve/Reject/Recall) Implement as scenario tests in `tests/contract/scenarios/` that run against a live backend. **Files**: New scenario test definitions per object ### Deficit C: No CI Quality Gate (drives ~40 issues) **Symptoms**: 8 frontend tests fail on main, integration tests fail on main, no lint in CI, no coverage reporting, deploy not gated on CI, go vet errors from missing mock methods **Root cause**: CI runs tests but doesn't enforce quality. Tests that fail on main are not blocking — they're ignored. No coverage threshold means coverage can only decrease. **Systemic fix**: 1. Fix all tests that fail on main (make green baseline) 2. Add `golangci-lint` step to CI (config exists, just not wired) 3. Add coverage reporting with ratchet (threshold = current level, can only go up) 4. Gate deploy on CI pass **Files**: `.github/workflows/ci.yml`, `Makefile` --- ## Revised Priority Framework Instead of "which cluster to fix first," the question should be: ### Level 1: Stop the Bleeding (1 week) **Fix tests on main + gate deploy on CI.** Why: Right now every PR is flying blind. You can't trust CI results. This must be fixed before ANY other work, because otherwise you can't verify fixes don't regress. ### Level 2: Build the Quality Gate (2 weeks) **Implement metadata quality validator + fix the gaps it finds.** Why: This fixes ~70 issues (labels, layouts, validation rules, picklists) AND prevents recurrence. The validator becomes part of bootstrap, catching future gaps automatically. ### Level 3: Complete Object Workflows (4 weeks) **Top-down: pick 3 objects (Account, Lead, Opportunity), make their full workflow work end-to-end.** Why: Fixing objects one-by-one with full workflow verification is more valuable than fixing horizontal slices (all layouts, all labels). A fully-working Account is more valuable than half-fixed everything. ### Level 4: Scale the Pattern (ongoing) **Extend to remaining objects using the same completeness contract.** Why: Once the pattern is proven on 3 objects, apply it to Campaign, Quote, Order, Contract, Case. --- ## Summary: What v2 Got Right vs What This Challenge Adds | Aspect | v2 Conclusion | Challenge Refinement | |--------|---------------|---------------------| | #1 problem | Layout dead code (32 issues) | **No object has a complete workflow** (layout is one symptom) | | Bottleneck | Technical point fixes | **Absence of metadata quality gate + completeness definition** | | Fix strategy | 3-phase horizontal (all layouts, all labels, all quotes) | **Vertical-first: make 3 objects fully work, then scale** | | Prevention | Not addressed | **Metadata validator at bootstrap + object workflow contracts** | | CI/testing | Listed as Tier 3 | **Should be Level 1 — you can't verify anything without green CI** | ### The Sharpest Reframe v2 asks: "Which bugs should we fix first?" This challenge asks: **"What system do we need so these bugs stop being created?"** Both matter. But if you only do v2's plan, you'll be back here in 3 months with 100 new issues of the same types. The systemic fixes (metadata validator, CI quality gate, object completeness contracts) are what break the cycle.