Live State Tracking

AI coding assistants have no memory between sessions. This system ensures every session starts with complete knowledge of what exists, preventing chaos and wasted effort.

Core Principle

The Two State Files

Both files live in the code repository root (not docs).

Why This Matters

Without State Tracking

With State Tracking

Session Start Ritual (MANDATORY)

Step 1: Read State (2 minutes)

# Read project state
cat PROJECT_STATE.md

Note these items:

• Current Phase
• Current Step
• Last Completed Step
• Locked Files list

Step 2: Read Inventory (2 minutes)

# Read what exists
cat WHAT_EXISTS.md

Note these items:

• Existing patterns to copy
• Existing endpoints/routes
• Database models in use

Step 3: Check Git Status (30 seconds)

git status
git log -3 --oneline

Verify clean state or understand uncommitted changes.

Step 4: State Understanding (MANDATORY)

Write this exact template:

> "I've read the state files. Here's my understanding:
> - Current Phase: [X]
> - Current Step: [Y of Z]
> - Last Completed: [description]
> - I will now work on: [description]
> - The gate for this step is: [gate criteria]
> - Pattern I'll copy from: [file path]
> - Files I expect to modify: [list]
>
> Is this correct? Should I proceed?"

Step 5: WAIT for Explicit Approval

Do NOT proceed until user confirms.

Pre-Code Verification Protocol (PCVP)

1. File Status Check

• Is this file in the "Locked Files" list? → If YES, STOP
• Have I read this file's current contents? → If NO, read first

2. Duplicate Check

• Does a similar file/component already exist?
• Search performed: [search term used]
• Similar files found: [list or "none"]

3. Pattern Check

• What existing file am I copying this pattern from?
• Pattern source: [file path]
• Deviation from pattern: [none / describe if any]

4. Gate Check

• What is the gate for this step?
• Gate: [describe verification criteria]

State your answers, then WAIT for approval before proceeding.

Duplicate Detection Protocol

Before creating ANY new file:

Search First (30 seconds)

# Before creating foo.controller.ts
find . -name "*.controller.ts" -type f
grep -r "FooController" --include="*.ts"

# Before creating FooService
grep -r "class.*Service" --include="*.ts" | head -20

Check WHAT_EXISTS.md

• Is this module already listed?
• Is there a similar endpoint?
• Is there a similar component?

Only Proceed If

• No duplicate found
• Pattern source identified in WHAT_EXISTS.md
• File path matches established structure

Pattern Match Enforcement

When copying a pattern, verify EXACT match:

If ANY element doesn't match, fix it before proceeding.

Common Deviations to Avoid

• Different import paths (use same structure)
• Different error message format
• Different response shape
• Additional methods not in pattern
• Missing validation that pattern has

30-Minute Checkpoint System

Set a timer. Every 30 minutes, STOP and verify:

Checkpoint Questions

1. Am I still working on the documented current step?
2. Have I drifted into "improvements" or "refactoring"?
3. Is my code following the exact pattern from WHAT_EXISTS.md?
4. Have I updated PROJECT_STATE.md recently?
5. Am I blocked? Should I ask for help?

If Any Answer Is Concerning

1. Stop current work
2. Update PROJECT_STATE.md with current status
3. Ask for clarification before continuing

Session End Ritual (MANDATORY)

Step 1: Update PROJECT_STATE.md

• Mark completed steps with ✅ and timestamp
• Update "Current Step" section
• Update progress percentage
• Add any new locked files
• Document blockers (if any)

Step 2: Run Final Verification

git status
npm test  # or applicable test command

Step 3: Write Handoff Note

Add to PROJECT_STATE.md under "What I'm About To Do":

• Exact next action
• Any blockers encountered
• Files that need attention
• Context next session needs

Step 4: Commit State Files

git add PROJECT_STATE.md WHAT_EXISTS.md
git commit -m "chore: update project state after [brief description]"

Error Recovery Protocol

When something breaks or goes wrong:

Step 1: STOP IMMEDIATELY

Do not try to "fix" the issue by making more changes.

Step 2: Document the Error

Add to PROJECT_STATE.md:

### ERROR ENCOUNTERED
- **Time:** HH:MM
- **Step:** XX
- **Error:** [describe what happened]
- **Files Modified Before Error:** [list]
- **Last Known Good State:** [commit hash or description]

Step 3: Assess Rollback Need

git status
git diff

Step 4: Rollback Options

Step 5: Resume Protocol

After recovery, restart Session Start Ritual from Step 1.

Anti-Improvement Pledge

If tempted to improve, ask instead:

"I notice [X] could be improved. Is this in scope for the current step? If not, I'll add it to a future enhancement list and continue with the current task."

Phase Completion Checklist

Before marking ANY phase complete:

• All steps have passing gates
• PROJECT_STATE.md updated:
  • Phase moved to "Completed Phases" section
  • All locked files listed
  • Key decisions documented
• WHAT_EXISTS.md updated:
  • New database models added
  • New API endpoints added
  • New frontend routes added
  • New patterns documented (if first of kind)
• Git operations:
  • All tests passing: npm test
  • Build succeeds: npm run build
  • Committed with message: "Phase XX: [Name] complete"
  • Tagged: git tag phase-XX-name
  • Pushed: git push && git push --tags

Quick Reference Card

Before Session

1. cat PROJECT_STATE.md
2. cat WHAT_EXISTS.md
3. git status
4. State understanding
5. WAIT for approval

Before Every Edit

1. Check locked files
2. Read current file contents
3. Search for duplicates
4. Identify pattern source
5. State gate criteria
6. WAIT for approval

After Every Step

1. Update PROJECT_STATE.md
2. Mark step ✅ with timestamp
3. Update progress %

End of Session

1. Update PROJECT_STATE.md
2. Write handoff note
3. git add && git commit

Related Documentation

• PROJECT_STATE.md Template - Copy this to your repository
• WHAT_EXISTS.md Template - Copy this to your repository
• AI Coding Agents Guide - Full development workflow
• Context Management - Session context