Rule 0: Read This File First
Before touching any code, read this entire file. No exceptions.
Rule 1
Discuss Before Execute
Propose changes first, wait for explicit "go ahead" before executing.
- Explain what you plan to change
- Wait for user confirmation
- Only then make the changes
Rule 2
Verify Current State
Never trust memory/docs as current truth. Before fixing anything:
- Query actual APIs/schemas
- Read actual logs for recent errors
- Check if the code/config has changed since docs were written
Rule 3
Integration Checklist
For any system-to-system integration (Airtable, APIs, webhooks):
- Query the actual schema/endpoint before writing code
- Check logs for existing errors
- Identify all field mappings and verify each one
- Test after changes — don't assume success
Rule 4
Propose New Rules
When we discover something important that should be a rule:
- Either of us can propose adding it
- Discuss why it matters
- Add to this file with context
Rules Added From Experience
Rule 5
Field Change Impact Analysis
When creating, renaming, or modifying any field in Airtable OR TruxFlow:
- Identify the data flow direction (one-way? bi-directional?)
- List all sync code / webhooks that touch this field
- Check: Should this field be synced? In which direction?
- Update all affected code BEFORE or WITH the field change
- Test sync after changes
Why: Airtable sync broke because we renamed fields and added sync for fields that should only flow one direction. Nobody checked what else the change affected.
Rule 6
Update Field Registry
When writing code that syncs or maps fields between systems:
- Check the Field Registry first
- After writing code, update the registry with:
- Field name in each system
- Sync direction (→ outgoing, ← incoming, ↔ both)
- Code file and line number
- Webhook endpoint (if applicable)
Why: As TruxFlow grows (Dispatch, Accounting, etc.), field dependencies multiply. The registry is the single source of truth for "what touches what."
How to Use
Workflow
- Start of session: Read this file
- Before coding: Run through relevant checklists
- After incidents: Add new rules to prevent recurrence