TMG Assessment Kit — Documentation

Design Philosophy

The assessment is built on three principles borrowed from the GSD (Git. Ship. Done.) framework's questioning methodology:

1. Thinking partner, not interviewer. The client often has a fuzzy picture of their own operations. The assessment helps them sharpen it — not just catalog it. Questions are open-ended, conversational, and probe vague answers rather than accepting them.
2. Make the abstract concrete. Instead of asking "rate your lead tracking pain 1–5," the assessment asks "walk me through what happens when a new lead comes in." The walk-through reveals the process, the breakpoints, and the unmade decisions.
3. Challenge vagueness. Short or vague answers trigger adaptive follow-ups that probe deeper. "It depends" or "not sure" are not accepted as final — they signal a gray area that gets surfaced and named in the report.

How the Kit Works

Client enters assessment (guided or self-serve)
        │
        ▼
  PHASE 1: Opening        ← Conversational, sets context
        ▼
  PHASE 2: Walkthrough     ← Process discovery via concrete scenarios
        ▼
  PHASE 3: Probes          ← Adaptive deep-dives, surface gray areas
        ▼
  PHASE 4: Domain          ← Industry-specific (Cannabis / Funeral) or generalized topic-driven (Other)
        ▼
  PHASE 5: Capacity        ← Budget, timeline, tech comfort
        ▼
  PHASE 6: Synthesis       ← Final framing questions
        ▼
  DIAGNOSTIC ENGINE        ← Scores clarity, ambiguity, readiness
        ▼
  DIAGNOSTIC REPORT        ← Consultation-style, not survey output

Adaptive Follow-Up Architecture

Each prompt can trigger adaptive follow-ups — additional questions that appear only if the client's answer meets certain conditions. This is the core of the Socratic approach.

Prompt: "Walk me through what happens when a new lead comes in"
        │
        ├── Answer mentions "memory" / "remember" / "no system"
        │   └── Follow-up: "When a lead doesn't convert right away,
        │       what happens to them?"
        │       └── Surfaces gray area: "Lead Nurture Strategy"
        │           → Critical, maps to CRM
        │
        ├── Answer mentions spreadsheet + other systems
        │   └── Follow-up: "How do you keep them in sync?"
        │       └── Surfaces gray area: "Data Architecture"
        │           → Significant, maps to CRM
        │
        └── Answer is clear but describes manual process
            └── Follow-up: "How much time does this take?"
                └── Signals automation candidate for AI Agents

Follow-ups can surface: gray areas (unmade operational decisions), system signals (weighted contributions to scoring), and clarity dimension scores (evidence about process definition).

Phase 1: Opening

Conversational. Sets context and establishes baseline clarity.

Phase 2: Walkthrough

Process discovery via concrete scenarios. The core GSD technique: "walk me through using this."

Phase 3: Probes

Adaptive deep-dives that surface operational decisions and measure clarity.

Phase 4: Domain (Industry-Specific)

Appears for matching industries, and — for any other industry — dynamically based on what the conversation revealed. Dedicated industries keep their own probes; everything else routes to generalized topic-based probes selected by rule-based keyword detection over the Phase 1–3 free-text (no LLM). Picking "Other" triggers a free-text follow-up that feeds both detection and the report narrative.

Cannabis Operators

Funeral Services

Other Industries (generalized, topic-driven)

For small_business, nonprofit, and "Other", these fire when a topic surfaces in the conversation (e.g. a pharmacy describing regulated inventory and batch tracking). Each mirrors its dedicated counterpart.

Phase 5: Capacity & Readiness

Phase 6: Synthesis

Diagnostic Engine

The engine measures three dimensions that together determine the recommendation — not just "what hurts" but "are you ready to fix it."

Operational Clarity (0–100)

Measures how well-defined the client's processes are. Scored across up to 15 dimensions:

Scored by: answer specificity (length, concrete steps), vague signals ("depends," "not sure," "varies"), specific signals ("first," "then," named tools), and select-answer patterns.

Operational Ambiguity (0–100)

Measures how many unmade decisions (gray areas) were surfaced. Each gray area is a specific operational decision the client hasn't made, mapped to a core system that would force the decision.

Score: Critical gray areas × 30 + Significant gray areas × 15, capped at 100.

AI Readiness (0–100)

Overall AI Readiness is the average of the four sub-scores.

Readiness Path Determination

System Scoring & Tiering

Each system receives a Fit Score (from accumulated signal weights) and an Ambiguity Score (from related gray area count × 25, capped at 100).

Diagnostic Report

The output is a consultation-style report, not a survey output. Contains:

1. 1. Diagnostic Summary — Narrative paragraph + headline scores (Clarity, Ambiguity, AI Readiness, Path)
2. 2. Key Findings — Bullet-pointed findings from the diagnostic
3. 3. Unmade Decisions — Each gray area with severity, description, related system, and decision needed
4. 4. Operational Clarity Scorecard — Visual bars across all dimensions with evidence
5. 5. AI Readiness Breakdown — Data, Process, Team, Budget cards
6. 6. Recommended Path — Foundation-First / Direct / Hybrid with reasoning
7. 7. System Recommendations — Dual fit/ambiguity scores, signals, related gray areas
8. 8. Next Steps — Four-step engagement roadmap

Delivery Modes

Industry-Specific Branches

Cannabis (METRC, 280E) and Funeral Services (case management, aftercare) probes are dedicated to their industries. All other industries — small_business, nonprofit, and "Other" — route to generalized Phase 4 probes selected dynamically by what the conversation revealed (rule-based topic detection over Phases 1–3, no LLM). Dedicated industries never receive the generalized probes (avoids overlap). Additional industries can be added either with a dedicated probe set (gated by appearsIf on industry) or by simply adding an option that reuses the generalized probes.

Technical Architecture

assessment-kit/
├── app/
│   ├── page.tsx                          # Landing page (mode selection)
│   ├── assessment/
│   │   ├── page.tsx                      # Suspense wrapper
│   │   └── AssessmentContent.tsx         # Conversation flow
│   ├── docs/
│   │   └── page.tsx                      # This documentation page
│   └── layout.tsx                        # Root layout
├── components/
│   └── DiagnosticReport.tsx              # Consultation-style report
├── lib/
│   ├── types.ts                          # Type system
│   ├── prompts.ts                        # Socratic prompt tree
│   └── engine.ts                         # Diagnostic scoring engine
└── package.json

Design Decisions Log

Open Items

1. 1. Data persistence — Assessment responses now persist to Neon Postgres via Drizzle ORM. Each answer autosaves; assessments resume by email (one per person); the finalized report is snapshotted as a stable, shareable artifact at /report/[id]. See DATABASE_LAYER_PLAN.md.
2. 2. Question review with Aaron — The prompt tree should be reviewed with Aaron's domain expertise (cannabis, funeral homes) for additional or revised probes.
3. 3. Scoring weight calibration — Signal weights are initial estimates. Real-world results will reveal which signals correlate with successful implementation. Weights are in lib/prompts.ts and lib/engine.ts.
4. 4. Visual branding — Currently dark theme with teal/blue accents. Can be updated to match TMG brand colors (dark navy with gold/orange highlights).
5. 5. Guided mode enhancements — Future: consultant notes field per question, ability to skip follow-ups, pre-assessment checklist.