forgejo-lila/lila
1
0
Fork 0
Code Issues 50 Pull requests Projects 1 Releases Packages Wiki Activity Actions
lila/documentation/ai-context/WORKFLOW.md
lila 7e0311683f updating documentation
2026-05-16 01:59:43 +02:00

11 KiB
Raw Blame History

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)