# Coding Workflow & Validation Discipline

> Follow this workflow EVERY TIME you write Jac code. No shortcuts.

---

## Before Writing Code

1. **Read `jac.toml`** — check npm deps, project config, entry point.
2. **Call `jac_docs(query)`** — look up syntax for what you're building. Do NOT guess.
3. **If existing project**: call `analyze_project(directory)` to understand structure.
4. **Call `jac_docs` again** before EACH new file type (`.jac` vs `.cl.jac` have different syntax).

---

## Build Order (fullstack apps)

1. `main.jac` backend first — nodes + endpoints
2. Hooks — `hooks/useX.cl.jac` (sv import from backend)
3. Leaf components — `Header.cl.jac`, `ItemCard.cl.jac` (no data logic)
4. Container components — `ItemList.cl.jac` (calls hooks, renders leaf components)
5. Layout — `Layout.cl.jac` LAST (imports child components)
6. App entry — `cl { def:pub app() }` in `main.jac`

**Build dependencies bottom-up.** Never import a file that doesn't exist yet.

---

## While Writing Code

- Use `write_code` / `edit_code` — they auto-run `jac_check` per file for syntax errors.
- Do NOT call `jac_check` or `jac check` manually.
- Do NOT use `run_command` for jac check.
- If `write_code`/`edit_code` report errors → call `jac_docs(query)` to look up correct syntax → fix → retry.
- Call `jac_docs` at least once every 3-4 tool calls. If unsure about ANY syntax, look it up immediately.
- Use ABSOLUTE file paths for all operations.

---

## After Writing ALL Files

### Step 1: Cross-file import check

Before validating, manually verify:
- Every `import from "..."` / `sv import from ...` references a file that exists
- sv import function names match actual `def:pub` names in `main.jac`
- Component imports use correct dot-levels (`.` same dir, `..` one up, `...` two up)
- No duplicate component names or endpoint names across files

### Step 2: Validate

Call `validate_project(directory)` ONCE after all files are written.
- It batch type-checks all `.jac` files
- It auto-fixes common patterns (root→root(), (?:)→[?:])
- It returns all type errors with hints

### Step 3: Fix and re-validate

- Read the report from `validate_project`
- Fix all remaining errors
- Call `validate_project()` again to confirm clean

### Step 4: Preview log check (fullstack apps)

- Read the LAST 50 lines of `.jac-preview.log`
- Look for: `[Client]`, `ERROR`, `Exception`, `undefined`, `module not found`
- Common runtime errors:
  - "module not found" → file doesn't exist OR stale HMR cache
  - "undefined" → missing prop, uninitialized state, wrong import
  - "Function X failed" → sv import name doesn't match backend def:pub
  - "422" → request body schema mismatch

---

## When Stuck

1. Call `jac_docs(query)` — look up the correct syntax
2. Call `analyze_project` or `find_symbol` — check existing patterns
3. If same error 2-3 times → `ask_question` to ask the user
4. If editing same file 3+ times → step back, check assumptions

---

## HMR "module not found" Fix

1. File exists but compiled JS is stale
2. Do trivial edit on the TARGET file (not the importing file) — add a blank line
3. HMR recompiles, import resolves
