forgejo-lila/lila
1
0
Fork 0
Code Issues 50 Pull requests Projects 1 Releases Packages Wiki Activity Actions

updating documentation

Browse source
This commit is contained in:
lila 2026-05-16 01:59:43 +02:00
parent 1ba57c7e9d
commit 7e0311683f
25 changed files with 2660 additions and 226 deletions
Download patch file Download diff file Expand all files Collapse all files

260
documentation/ai-context/WORKFLOW.md Normal file
View file

@ -0,0 +1,260 @@
# 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)
```