# Lessons

Updated: 2026-02-24

## Context / Mistake / Rule

1. Context: Documentation updates during rapid iteration
   Mistake: File path assumptions drifted across turns
   Rule: Verify target files with `find` and `wc -l` immediately after each save operation.

2. Context: Mixed policy documents (`agents.md`, `CLAUDE.md`, project requirements)
   Mistake: Source-of-truth order remained implicit
   Rule: Anchor task execution to `docs/requirements.md`, then align secondary operating docs to that baseline.

3. Context: AI endpoint review for MVP hardening
   Mistake: Utility regex and service size limits were under-enforced during fast delivery
   Rule: Add deterministic edge-case tests for parser heuristics and enforce file-size split before declaring MVP complete.

4. Context: Local MVP validation with UI-gated features
   Mistake: Test instructions skipped the exact in-app location and feature visibility conditions
   Rule: Document one deterministic URL path plus visibility prerequisites whenever a feature is behind settings or permissions.

5. Context: Railway deployments from local `railway.toml`
   Mistake: Start command drifted to a non-existent runtime path and caused repeated crash loops
   Rule: Keep `railway.toml` `startCommand` aligned with Docker runtime entrypoint and verify with deployment logs after every command change.

6. Context: Quality review requests with explicit target scores
   Mistake: Initial assessment did not immediately convert score gaps into concrete code-level remediation tasks
   Rule: For any score target, map each category gap to a named patch + test gate before returning a status update.

7. Context: AI routing hardening in deterministic tool orchestration
   Mistake: Considered model-structured output guards before validating actual failure surface
   Rule: When tool routing is deterministic, prioritize planner fallback correctness and executor policy gating before adding LLM classifier layers.

8. Context: Open-source submission strategy after publish constraints
   Mistake: Treated npm publication as the only completion path for contribution evidence
   Rule: When package publication is blocked, ship the tool in-repo and open upstream PRs in high-signal repositories to preserve external contribution progress.

9. Context: Memory feature validation after chat/session persistence rollout
   Mistake: Session-scoped memory shipped without an explicit user-scoped preference path for cross-session continuity.
   Rule: When memory requirements mention user preferences, implement and test both session memory and user-level memory keyed independently from session IDs.