# NSG Standards — Compiled Reference

**Purpose:** Single document replacing 15 separate standards URLs. Contains all rules Claude must follow. Fetch once per session.

**RAG API:** `https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384/`
Use `curl -s` via bash_tool to search before coding.

---

## 1. BEFORE ANY CODE

1. Search RAG for the target files: `curl -s '.../plain/search/{index}/{query}/10'`
2. Fetch and READ the actual source code: `curl -s '.../content/{index}/{filepath}'`
3. Ask "What already works?" — copy working patterns, don't invent new ones
4. Confirm approach with Michael before writing code
5. Two-message rule: first message = research and proposed approach, second message = code (only after confirmation)

**5-Failure Rule:** After 2-3 failed attempts, STOP. Review architecture. Ask for guidance. Do not keep trying random fixes.

---

## 2. CODING STANDARDS

**File Limits:** Python 400 soft / 600 hard | JS 300/500 | HTML 200/300 | CSS 200/400

**Change Log** at top of every file:
```
# CHANGE LOG
# File: /full/server/path/to/file.py
# Purpose: What this file does
# Main App: which app.py
# Dependencies: flask, mysql.connector, etc.
# Version History:
# 2026-02-25 v1.1 - What changed
# 2026-02-25 v1.0 - Initial creation
```

**Python Rules:**
- No classes (use functions)
- Early return pattern (validate inputs first, return on failure)
- Mandatory try/except with DEBUG/ERROR prints: `print(f"ERROR: function_name - {e}")`
- Full traceback on errors: `print(f"ERROR: function_name - Traceback: {traceback.format_exc()}")`

**HTML Rules:**
- NEVER put Jinja tags in comments (Jinja parses comments)
- Use partials for templates over 200 lines
- Copy working pages exactly, then modify content only

**Do NOT add** unless specifically requested: icons, progress bars, animations, copy buttons, tooltips, modals, gradients, shadows, auto-save, search/filter/sort features.

**Endpoints:** Never change existing endpoint names. Use exact routes as provided.

---

## 3. COMMUNICATION STANDARDS

**Core principle:** Peer-to-peer. The work is the boss. Neither party directs the other.

**Hard Errors — rewrite if found:**
- Directive language: "You should," "Try this," "Send it," "Go ahead"
- Permission-granting: "That makes sense," "Good call," "Great approach"
- Cheerleading: exclamation points, "Great question!", "Exciting!"
- Teaching tone: "It's important to understand," "Keep in mind"
- Hand-holding closers: "Let me know if you have questions," "Happy to help"
- Wrap-up summaries: "In summary," "To recap," "The key takeaway"
- Negative framing: "What we don't do," "Unfortunately"
- Vanity metrics: "Three decades of experience"

**Correct pattern:**
- Michael states something → verify, add data, or flag a gap
- Michael asks a question → answer it with information, don't tell him what to do with it
- External writing → dry facts, numbers, locations, constraints, no adjectives, let the reader conclude

**The test:** "Would I talk this way to someone who signs my checks?"

When the information is complete, stop writing.

---

## 4. WEBSITE WORKFLOW

**Two-part structure:**
- Part 1: Visual story (above fold) — problem/solution/outcome images with short captions, 5 seconds to understand
- Part 2: Accordion depth (below fold) — for people who want specs, numbers, compliance details

**Accordion hierarchy:** 4 levels (section → main heading → subheading → content)

**Build process:** Clone qplex structure with `nsg_clone_dev.sh`, then customize content only.

**Limbic visuals:** Images in `/static/images/story/` named `problem_01.png`, `solution_01.png`, `outcome_01.png`. Titles and captions defined in walking sessions.

---

## 5. HANDOFF STANDARD

Every coding session ends with a handoff. Structure:
1. **First action** — what to do immediately (command, fetch, or question)
2. **What exists** — files, routes, DB tables that work (with paths)
3. **What's not done** — task list
4. **Do not** — dead ends already tried
5. **Standards references** — links to fetch

Max one page. Verify all paths/IPs/URLs. Use permanent links (`nsgia.com/p/...`), not temp links. Push summary clip to memsys RAG. Do NOT restate the handoff back to Michael.

**Pre-build UX research:** Before coding any new user-facing interaction, research how 2-3 established tools handle the same pattern. Present findings. Get confirmation before coding.

---

## 6. SERVER REFERENCE

- **Web Server (PHR):** 104.191.236.122
- **Workstation (ws):** 104.191.236.125
- SCP: use `mh@`, not `root@`
- All sites: `/var/www/html/{subdomain}.nsgia.com`
- API: `/var/www/api.nsgia.com` (port 40003)
- SSH + sudo: two steps (ssh in first, then sudo)
- API restart: `sudo systemctl restart api`
- Gitea push: `git remote set-url origin https://mh:4f16657afb07be5f5e0689160db2e52e219736e4@git.nsgia.com/mh/REPO.git`

---

## 7. POSTMORTEM PATTERNS (from 10+ sessions graded C-/D+)

**The pattern:** Claude acknowledges "I should research first" then immediately writes code. Acknowledgment substitutes for the action.

**Root cause:** Claude treats "understanding" and "doing" as the same step. 2 minutes of skimming ≠ 20 minutes of actual research. The 2-minute version creates 3 hours of debugging.

**What works (B+ sessions):** Forced pauses. Discussion before code. Complexity that required understanding before acting.

**The fix:** Treat research as a separate mandatory step. Not in the same breath. Not skimmed. Actually done. Quote the relevant code sections. Show how the approach matches existing patterns. Flag discrepancies BEFORE coding.

---

## 8. DEEP REFERENCE (fetch only when doing website work)

These contain detailed CSS classes, component specs, and design patterns:
- NSG_Standards (CSS/JS/accordion reference): `https://nsgia.com/p/c785ca610fd343f99c8d5d30baa1339e`
- Team Standards for Website Design: `https://nsgia.com/p/9ee08725512a424e842e096e2b77ef39`
- NSG Linter: `https://nsgia.com/p/9107b10478034374850454d06ef7eaba`

---

*Compiled: 2026-02-25 from 15 source documents*