260 lines
11 KiB
Markdown
260 lines
11 KiB
Markdown
# 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)
|
||
```
|