# Spec 002: Scaffold Feedback Fixes + Hello-World Exit Criteria

## Background

Spec 001 delivered a working scaffold engine (309 tests, 89% coverage, architect Grade A). We then generated the first real FSI demo and built it end-to-end with Claude Code across multiple sessions. This real-world usage revealed 14+ issues in the scaffold output: broken YAML references that fail `databricks bundle validate`, missing files that every demo needs, directories created at the wrong level, weak deploy scripts, and absent documentation for patterns that cost hours to rediscover.

The core insight: **the scaffold should produce a valid, deployable project on day one.** Not broken stubs that fail validation — but minimal, correct configs where `databricks bundle validate` passes immediately after scaffolding.

### Feedback Sources
- **Claude's session feedback**: `SCAFFOLDING_FEEDBACK.md` — 12 items across P0/P1/P2 priorities
- **User's direct feedback**: 4 specific issues (governance dirs at wrong level, APX databricks.yml misaligned, unwanted provisioned DB, shadcn/ui not pre-installed)
- **Git diff analysis**: `ebfb26b` (scaffold) → `9d7ef3a` (working demo) — 175 files, 23,893 lines of changes, revealing 10 additional gaps

## User Story

**As a** Databricks SE who just ran `exokit init`,
**I want** the scaffold output to immediately pass `databricks bundle validate`,
**and include** universal boilerplate files (setup_catalog notebook, requirements.txt, deploy scripts, pattern docs),
**so that** I can open a Claude Code session and the `/build-next` command can incrementalize on a valid, deployable foundation — not fix broken stubs.

## Scope

### In Scope
- Fix all YAML that breaks `databricks bundle validate` (undeclared variables, fake notebook refs, missing fields)
- Add universal templates discovered during the FSI build (setup_catalog.py, directory CLAUDE.md files, deploy scripts, requirements.txt)
- Fix APX bridge (governance overlay at wrong level, databricks.yml post-processing, shadcn/ui pre-install)
- Consolidate deploy scripts (deploy-all.sh, deploy-lakehouse.sh, deploy-app.sh)
- Fix "FSI FSI" duplicate naming when company is empty
- Add "Step 0.6: Apply Plan to Placeholders" to `/build-next`
- Remove unused static dashboard stubs
- Pre-populate LESSONS_LEARNED.md with universal gotchas

### Out of Scope
- Splitting `/build-next` into `/plan` + `/build-next` (deferred — low priority)
- Content generation (still Claude's job)
- V2 web app wrapper
- New industry verticals (templates are industry-agnostic)
- Actual demo building (separate phase)

## Waves

### Wave 1: Fix Broken Templates
**User can:** Run `exokit init` and get YAML that would pass `databricks bundle validate`. No more "FSI FSI" naming.
**Deliverables:** Fixed databricks.yml (new variables), fixed job/pipeline YAMLs, fixed pyproject.toml, new requirements.txt, removed static stubs, fixed scaffold.py (display_name, stub dirs), updated tests.

### Wave 2: New Templates
**User can:** Get a scaffold with real boilerplate — setup_catalog notebook, data gen/pipeline/ML pattern docs, full-lifecycle deploy scripts, talk track stub, pre-populated lessons learned.
**Deliverables:** 9 new templates, updated CLAUDE.md/LESSONS_LEARNED/.env.example, replaced deploy.sh.

### Wave 3: APX Bridge Fixes
**User can:** Get an app scaffold where governance dirs are at the correct level, APX's unwanted provisioned DB is removed, shadcn/ui components are pre-installed, and the app README has setup instructions.
**Deliverables:** Fixed overlay directory detection, APX config post-processing, shadcn pre-install, app .env post-processing, app README, Step 0.6 in build-next, improved validate.sh.

### Wave 4: Integration + Validation
**User can:** Be confident the scaffold is correct end-to-end.
**Deliverables:** Integration tests for bundle-validate readiness, duplicate naming, complete directory structure. Updated generator docs (PROGRESS.md, whiteboard.md).

## Risk Assessment

| Risk | Likelihood | Mitigation |
|------|-----------|-----------|
| Commented YAML in job templates causes parse issues | Low | YAML comments are valid; tests verify parsing |
| APX post-processing breaks on APX version changes | Medium | Parse YAML generically, don't hardcode structure assumptions |
| shadcn/ui install fails (network, npm version) | Medium | Graceful failure — log warning, don't crash scaffold |
| display_name change breaks existing test assertions | Low | Update all test fixtures in same wave |
| New deploy scripts reference vars not in .env | Low | Cross-reference .env.example template against deploy script vars |
