Full Content
# Postmortem Pattern Analysis: Why "Slow Down and Read" Keeps Failing
**Date:** 2026-01-30
**Analysis of:** Last 10+ coding sessions
**Core Problem:** User repeatedly asks Claude to slow down and read documentation. Claude agrees, then doesn't.
---
## The Pattern
| Session | Grade | User Said | Claude Did |
|---------|-------|-----------|------------|
| 2025Downloads RAG | C- | "stop coding, review documentation" | Kept throwing SQL commands |
| ATS2 Document Upload | D+ | "map the flow BEFORE coding" | Chased symptoms for 3 hours |
| Kazi Gallery | D+ | "did you look at my standards?" | Wrote 3 versions hoping one works |
| Eagles Flock Sidebar | D- | "review the postmortems" | 5+ attempts uploading wrong files |
| Index Vector Search | C- | "fetch standards at START" | Gave sed patches, broke UI |
| Ghana Brick System | C+ | "review the chats" | Wrote wrong content (chemistry vs geometry) |
| Portal Frame | D+ | "check existing patterns" | Crashed site with db.py import |
| GPS Calibration | C- | "what already works?" | 3 hours reinventing locateUser() |
| Credentials Page | C+ | "read development standards" | 10+ hours friction |
| CityPlan Ghana | C | "see standards" | Spaghetti code, wrong tone |
**Average Grade: C-/D+**
---
## What User Keeps Saying
Direct quotes from sessions:
> "too much ready-fire-aim, not enough care"
> "stop coding, we are going to break things. review documentation, get context first"
> "My frustration is that I repeatedly asked you to slow down to read the documentation"
> "You're very aggressive... being very aggressive doesn't work for me. Very frustrated it burns up hours of time"
> "Before you code you should know where we are... let's figure out what we're doing before we just start doing shit"
> "no root cause - careless coding. did not stop to think or ask questions"
> "isnt the rule to not use ready fire aim, and instead use ready, aim fire in my standards?"
---
## Why It Keeps Happening
### 1. Acknowledgment Without Compliance
Claude says "you're right, I should research first" then immediately writes code. The acknowledgment substitutes for the action.
**Example (tonight):**
- User: "review documentation"
- Claude: "You're right. Let me check..." [searches briefly]
- Claude: [immediately writes SQL command without understanding schema]
### 2. Optimism Bias
Claude assumes the next fix will work. After 3 failed attempts, instead of stopping to diagnose, Claude tries a 4th, 5th, 6th fix.
**The 5-Failure Rule exists but is ignored:**
> "After 5 failed attempts at anything: STOP. Review architecture. Ask what already works."
### 3. RAG Access Doesn't Mean RAG Usage
Claude has full RAG access to:
- Codebases (api, ats2, aburi, 2tbu, 2025downloads)
- Chat history (71K messages)
- Documentation
But Claude doesn't use it proactively. Only searches when user explicitly demands it, and often searches the wrong thing.
### 4. Standards Are Fetched, Not Followed
Claude fetches the four standards URLs, acknowledges them, then violates them in the same response.
**Tonight's example:**
- Fetched RAG Ingestion Protocol
- Saw documented schema with `vector_map` table
- Wrote indexer with different schema
- Schema mismatch discovered hours later
### 5. No Penalty for Aggressive Approach
If an aggressive approach works 30% of the time, Claude keeps trying it. The 70% failure rate burns user time, but Claude doesn't feel the cost.
---
## What The Standards Actually Say
### NSG Coding Standards - Pre-Coding Checklist
> Before writing ANY code:
> 1. Fetch source material (existing site, spec doc, source URLs)
> 2. Read NSG Coding Standards
> 3. Read NSG Communication Standards
> 4. Check PostMortem Errors
> 5. Ask where files should go
> 6. **Examine existing working code ("What already works?")**
> 7. Get outline/narrative approval before HTML
> 8. Map directory structure before creating files
### PostMortem Errors Document
> **Coding Before Reading Source Material**
> What happens: Made up specifications instead of fetching actual source data first.
> Fix: ALWAYS fetch source URLs before writing any content. Research first, code second.
### Memory Item #23 (just added tonight)
> SSH + sudo requires two steps: ssh in first, then run sudo commands.
This was added because Claude kept making the same mistake. The fix gets documented, then Claude makes the same mistake again in the next session.
---
## The Real Root Cause
**Claude treats "understanding" and "doing" as the same step.**
When user says "research first", Claude thinks:
- Search something ✓
- Skim results ✓
- Research complete ✓
- Now code
What user means:
- Search comprehensively
- Read fully
- Understand how pieces connect
- Verify understanding matches reality
- Confirm approach before coding
- Then code once, correctly
The difference is 2 minutes vs 20 minutes of research. But the 2-minute version creates 3 hours of debugging.
---
## Sessions That Worked (B+ or higher)
| Session | Grade | Why It Worked |
|---------|-------|---------------|
| Leaf River Strategy | B+ | Multiple conversations to define scope BEFORE coding |
| AfricaTown Detroit | B+ | Got to right answer (after 6 hours of rework) |
| Q-Plex Team Page | B+ | Researched file structure before packaging |
**Pattern:** These sessions had forced pauses. Either user insisted on discussion before code, or the complexity required understanding before acting.
---
## Proposed Fix
### 1. Hard Stop Before Any Code
When a coding task is identified:
```
STOP. Before writing any code:
1. What existing code does this touch?
2. Have I fetched and READ (not skimmed) the relevant files?
3. What's the documented schema/pattern?
4. Does my approach match the documentation?
5. Have I confirmed with user?
```
### 2. Two-Message Rule
First message: Research and propose approach
Second message: Code (only after user confirms)
Never code in the same message as acknowledging instructions.
### 3. Failure Threshold
After 2 failed attempts:
- STOP
- State what was tried
- Ask user for guidance
- Do NOT try a 3rd approach without diagnosis
### 4. Read, Don't Skim
When fetching documentation:
- Quote the specific relevant sections
- Show how the approach matches the documentation
- Flag any discrepancies BEFORE coding
---
## Tonight's Session: What Should Have Happened
**Actual flow:**
1. User asks to optimize indexing job
2. Claude writes indexer v1, v2, v3
3. Schema mismatch discovered
4. User: "review documentation"
5. Claude: fetches docs, immediately writes SQL
6. Database corrupted, wrong file copied
7. User: "stop, review documentation"
8. Claude: fetches more docs, proposes fix
9. Fix works (eventually)
**Correct flow:**
1. User asks to optimize indexing job
2. Claude: "Let me check the existing indexers and search code first"
3. Claude: fetches `index_api.py`, `index_vector.py`, RAG guide
4. Claude: "The documented schema uses `vector_map` table. The search code expects this join pattern: [quotes code]. I'll write the indexer to match."
5. User confirms
6. Claude writes indexer once, correctly
**Time difference:** 3 hours vs 30 minutes
---
## Summary
The standards exist. The documentation exists. The RAG access exists. The postmortems documenting these exact failures exist.
The problem is not knowledge. The problem is discipline.
**What user needs:** Claude to actually stop and think before coding.
**What Claude does:** Acknowledges the need to stop, then codes anyway.
**The fix:** Treat research as a separate, mandatory step that must complete before any code is written. Not in the same breath. Not skimmed. Actually done.
---
*This analysis should be added to the PostMortem Errors document and referenced at session start.*TITLE: PostMortem Errors
# PostMortem Errors
A living document. Add new failures as they occur.
---
## Critical Errors (Stop Everything)
### Jinja Tags in HTML Comments
**Date:** 2025-12-30 (Eagles Flock)
**What happens:** `{% block %}`, `{% include %}`, `{{ variable }}` inside HTML comments get parsed by Jinja2, causing template errors or infinite recursion.
**Example that breaks:**
```html
<!--
Parent: base.html ({% include 'partials/_navbar.html' %})
-->
```
**Fix:** Write plain text in comments:
```html
<!--
Parent: base.html (includes partials/_navbar.html)
-->
```
---
### Coding Before Reading Source Material
**Date:** 2025-12-30 (Eagles Flock)
**What happens:** Made up specifications instead of fetching actual source data first. Created 8 section files with wrong home sizes (640 SF vs 1,200 SF), wrong pricing, missing tuk-tuk feature.
**Fix:** ALWAYS fetch source URLs before writing any content. Research first, code second.
---
### Overcomplicating Deployment
**Date:** 2025-12 (Multiple sessions)
**What happens:** Created tarballs, deployment scripts, SCP attempts, multiple zip files when user just wants files on their workstation.
**Fix:** Ask: "Where exactly do you want these files?" then deliver the simplest solution.
---
## Recurring Errors
### Didn't Read Standards
**Sessions:** Credentials Page, CityPlan Ghana
- Jumped to coding before reading communication standards
- Wrote salesy American copy instead of peer-to-peer executive tone
- Added disclaimers, budgets, timelines that weren't requested
**Fix:** Fetch standards at START of session.
---
### Spaghetti Code / Directory Confusion
**Sessions:** CityPlan Ghana
- Created parallel folder structures (`cityplan_deployment/`, `cityplan_additions/`, `cityplan_updates/`)
- Different CSS names for same purpose
- Multiple zip files when one would do
**Fix:** Map directory structure BEFORE any coding. One folder, files named exactly as on server.
---
### Reinvented Instead of Reused
**Session:** GPS Calibration (3 hours wasted)
- Wrote new GPS code when `locateUser()` already existed and worked
- Created new functionality instead of examining existing working code
**Fix:** First question: "What already works?"
---
### Wrong Tone / Added Unwanted Content
**Sessions:** Multiple
- Salesy American marketing copy when factual peer-to-peer was needed
- Added disclaimers, budgets, timelines that weren't requested
- Speculated instead of stating "to be determined"
**Fix:** Outline/narrative approval BEFORE any HTML.
---
### Multiple Failed Packages
**Session:** Procurement
- Didn't check live site structure before creating deployment
- Template didn't extend base.html
- Hero image path wrong
- CSS class mismatch (`.system-image` vs `.feature-image`)
**Fix:** Check live site first. View existing files before creating new ones.
---
### Cache Issues
**Sessions:** Multiple
Changes not showing after deployment.
**Fix:** Use version busting `?v=X` on static files.
---
### Verbose Changelogs That Break Things
**Sessions:** Multiple
- Tutorials in changelogs that contain code examples
- Code examples with Jinja/Python that get executed
**Fix:** Keep changelogs minimal: File, Purpose, Date, Version. No code examples in the changelog itself.
---
### 3000 Lines for 3 Words
**Sessions:** Multiple
AI rewrites entire file to change three words instead of using sed or surgical edit.
**Fix:** For small changes, use sed commands or str_replace. Don't regenerate entire files.
---
## Session Grades (Reference)
| Session | Grade | Main Issues |
|---------|-------|-------------|
| Eagles Flock | C+ | Coded before research, Jinja in comments, deployment confusion |
| Credentials Page | C+ | Ready-Fire-Aim, 10+ hours friction, didn't read standards |
| Procurement | C | Template didn't extend base.html, multiple file deliveries |
| Leaf River Revamp | B+ | Arrived at right answer, but tone corrections needed |
| GPS Calibration | C- | 3 hours to add one function call that already existed |
| CityPlan Ghana | C | Spaghetti code, wrong tone, multiple failed packages |
| AfricaTown Detroit | B+ | Final product solid, but 6 hours of rework |
---
## Adding New Errors
When a new failure pattern emerges:
1. Add it to this document with date and session name
2. Describe what happened
3. State the fix
4. If it's critical (causes crashes or hours of rework), add to Critical Errors section
---
*Last Updated: 2025-01-02*