# Workflow — Working with LLMs on Lila > **Purpose:** The process for using AI assistants effectively on this codebase. Covers task scoping, context selection, conversation management, verification, and doc updates. Complements `prompts/meta.md` (which covers prompt templates and methodology). > **Last updated:** 2026-05-15 --- ## Before Starting a Task ### 1. Define the Task Write a clear, specific description in 1–2 sentences. Avoid vague goals. **Bad:** "Fix multiplayer" **Good:** "Handle the case where a player disconnects mid-game and reconnects within 10 seconds — restore their game state without restarting the round." ### 2. Fill Out `99-current-task.md` Copy `documentation/ai-context/99-current-task.md` and fill in: - What you're building/fixing - Which parts of the codebase it touches (check the boxes) - Known files already involved - Constraints (must haves, nice to haves, must not break) - Definition of done This forces you to scope the task before involving the LLM. ### 3. Select Context Files Don't feed all AI-context files for every task. Pick the minimum the LLM needs. | Task Type | Feed These Files | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Frontend-only (UI component, route, styling) | `00-project-overview.md` + `03-api-contract.md` + `99-current-task.md` | | Backend-only (new endpoint, service logic, model query) | `00-project-overview.md` + `01-architecture.md` + `02-data-model.md` + `99-current-task.md` | | Full-stack feature (touches API + frontend + schema) | `00-project-overview.md` + `01-architecture.md` + `02-data-model.md` + `03-api-contract.md` + `99-current-task.md` | | WebSocket / multiplayer | `00-project-overview.md` + `04-websocket-protocol.md` + `99-current-task.md` | | Data pipeline (Kaikki, enrichment, sync) | `00-project-overview.md` + `05-data-pipeline.md` + `99-current-task.md` | | Deployment / infrastructure | `00-project-overview.md` + `06-deployment.md` + `99-current-task.md` | | Auth / security | `00-project-overview.md` + `03-api-contract.md` + `99-current-task.md` | | Cross-cutting refactor | `00-project-overview.md` + `01-architecture.md` + `02-data-model.md` + `03-api-contract.md` + `99-current-task.md` | **Always include:** `00-project-overview.md` (ground truth) and `99-current-task.md` (task scope). **Never include:** `prompts/meta.md` (that's for you, not the LLM). ### 4. Check for Decision Conflicts If the task touches any area from the Decision Index in `00-project-overview.md`, also feed the relevant section from `documentation/DECISIONS.md`. Examples: - Changing ORM or query patterns → feed `DECISIONS.md` → ORM section - Adding a new WebSocket library → feed `DECISIONS.md` → WebSocket section - Changing auth provider → feed `DECISIONS.md` → Auth section --- ## During the Task ### 5. Feed Context in Order ``` 1. 00-project-overview.md 2. Relevant domain file(s) (01–06) 3. 99-current-task.md (filled out) 4. [Optional] Relevant DECISIONS.md section 5. [Optional] Specific code files the LLM asks for ``` **Why this order:** The LLM sees the big picture first, then the domain details, then the specific task. This reduces hallucination. ### 6. Start with the Base Prompt Use the template from `prompts/meta.md`: ``` I'm working on Lila, a vocabulary learning app. Here's the project context: [PASTE: selected context files] My current task: [from 99-current-task.md] Please follow these rules: [1–8 from prompts/meta.md Base Prompt Template] ``` ### 7. Work File-by-File, Section-by-Section The LLM will suggest files to modify. Go through them one at a time: 1. **LLM explains the change** — concept first, code second 2. **You review** — does this make sense? Does it violate any constraints from 99-current-task.md? 3. **LLM shows the code** — section by section, not the whole file at once 4. **You apply** — copy-paste into your editor, don't let the LLM write files directly 5. **You verify** — TypeScript compiles, tests pass, manual check **Rule:** Never let the LLM modify more than one file before you review it. ### 8. Verify LLM Assumptions LLMs hallucinate file paths, schema shapes, and API endpoints. Periodically ask: > "Which files from the context did you actually look at?" > "What schema from packages/shared are you using here?" > "Show me the exact Zod schema for this request body." If the LLM's answer doesn't match the context files, correct it immediately. Wrong assumptions compound. ### 9. When to Start a New Conversation Start a fresh chat when: | Scenario | Why | | ------------------------------ | -------------------------------------------------------------------------------------------- | | Conversation exceeds ~25 turns | LLM coherence degrades; starts contradicting earlier context | | Task pivots significantly | "We were fixing a bug, now we're redesigning the feature" — fresh context prevents confusion | | LLM seems confused | Repeating questions, forgetting constraints, suggesting things already ruled out | | You took a break > 2 hours | Context window state is opaque; safer to restart | | Multiple failed attempts | The LLM is stuck in a bad pattern; reset gives it a clean slate | **How to restart:** Paste the same context files + updated 99-current-task.md (mark what's already done). Summarize progress in 2–3 sentences. ### 10. Handle Multi-File Changes For tasks touching 3+ files, establish a sequence: ``` 1. Shared schemas (packages/shared) — foundation everything else depends on 2. Database models (packages/db) — if schema or queries change 3. Backend service + controller (apps/api) — business logic 4. Backend tests (apps/api) — verify the service 5. Frontend API client + types (apps/web) — consume the new contract 6. Frontend components (apps/web) — UI changes 7. Frontend tests (apps/web) — verify the UI 8. Integration / e2e tests — full flow ``` **Exception:** If the task is frontend-only, skip steps 2–4. If backend-only, skip 5–7. Tell the LLM: "We'll go in this order. Start with [file]." --- ## After the Task ### 11. Final Verification Before declaring done: - [ ] `pnpm typecheck` passes (no TypeScript errors) - [ ] `pnpm test` passes (all tests green) - [ ] `pnpm lint` passes (no ESLint errors) - [ ] Manual verification in dev environment - [ ] No console errors in browser - [ ] No server errors in API logs ### 12. Ask for Doc Updates Prompt the LLM: > "Review the post-work checklist in prompts/meta.md. Which documentation files need updates based on what we just changed?" Expected output format: ``` - FILE: documentation/STATUS.md — REASON: Guest play flow is now live - FILE: documentation/ai-context/03-api-contract.md — REASON: New endpoint added - FILE: packages/shared/src/schemas/game.ts — REASON: New schema added ``` ### 13. Update Docs Yourself The LLM suggests; you apply. Docs are your responsibility, not the LLM's. Priority order: 1. `STATUS.md` — if "what works today" changed 2. `BACKLOG.md` — if a task was completed or discovered 3. `packages/shared/src/schemas/*.ts` — if request/response shapes changed 4. `ai-context/*.md` — if architecture, API, or protocol changed 5. `DECISIONS.md` — if you made a new architectural choice 6. `README.md` — if quickstart or stack changed ### 14. Generate Ticket File (If Significant) For completed tasks, create a ticket in `documentation/tickets/`: | Prefix | Use when... | Example | | -------- | ---------------------------------------------------- | ------------------------------------- | | `adr-` | Decision between options with long-term consequences | `adr-websocket-reconnect-strategy.md` | | `feat-` | New feature shipped | `feat-guest-play.md` | | `fix-` | Bug fixed | `fix-race-condition-lobby-join.md` | | `chore-` | Routine maintenance, refactoring, tooling | `chore-batch-distractor-queries.md` | **Ticket contents:** - What was done (summary) - Why it was needed (context) - What files changed (list) - Any follow-up work (notes) - Setup guide if applicable (how to verify it works) --- ## Common Anti-Patterns | Anti-Pattern | Why It Fails | Fix | | ------------------------------------------- | ----------------------------------------------- | ------------------------------------------------ | | Feeding all ai-context files for every task | Bloated context, LLM loses focus, wastes tokens | Use the file selection table (step 3) | | Letting the LLM write files directly | You don't understand the code, can't debug it | Copy-paste into your editor, review line by line | | Skipping verification | "It compiles" ≠ "it works" | Run tests, manual check, no console errors | | Not updating docs | Future You is confused, LLMs get stale context | Post-work checklist is non-negotiable | | One long conversation for everything | LLM forgets constraints, contradicts itself | Restart at ~25 turns or on pivot | | Accepting code you don't understand | You can't maintain it, can't explain it | Ask "explain this line" until you do | --- ## Quick Reference ### File Selection Cheat Sheet ``` Frontend only → 00 + 03 + 99 Backend only → 00 + 01 + 02 + 99 Full-stack → 00 + 01 + 02 + 03 + 99 Multiplayer/WS → 00 + 04 + 99 Data pipeline → 00 + 05 + 99 Deployment → 00 + 06 + 99 Auth → 00 + 03 + 99 Big refactor → 00 + 01 + 02 + 03 + 99 ``` ### Conversation Restart Template ``` I'm continuing work on Lila. Here's the current context: [PASTE: 00-project-overview.md] [PASTE: relevant domain file(s)] Previously, we [brief summary of what was done]. Current task: [updated 99-current-task.md, marking completed items] Let's continue from [specific file/section]. ``` ### Verification Checklist ``` □ pnpm typecheck □ pnpm test □ pnpm lint □ Manual dev verification □ No browser console errors □ No server errors □ Doc updates applied □ Ticket file created (if significant) ```