norm-claude 0.1.7

Situational awareness layer for Claude Code with auto status-lite reports, interactive brainstorming mode, and structured error analysis - designed for lawyers and coding novices

Norm Mode for Claude Code

Situational awareness for coding-novice lawyers using Claude Code.

Norm Mode is a prompt kit + CLI wrapper that transforms Claude Code into a reassuring, explicit tool for people who aren't programmers. It provides:

• Automatic status-lite reports after code changes (40-60 words: what we did, what changed, how to undo)
• Interactive brainstorm mode to develop developer-ready specs through one-question-at-a-time sessions
• Full STATUS reports on-demand (120-160 words with 7 sections: what changed, what didn't, how to undo)
• Fixed schemas for consistency (same structure every time)
• Risk transparency (Low/Medium/High with reasoning)
• No assumptions (jargon explained inline, git not required)
• ERROR_OPINION reports that translate technical errors into legal-opinion style analysis

---

Quick Example

Without Norm Mode:

User: Install pandas
Claude: [installs pandas]

User thinks: "What just happened? Did it work? What changed? Can I undo this?"

With Norm Mode:

User: Install pandas
Claude: Before I install pandas, here's what will happen:

**What Will Change:**
• Python library "pandas" will be downloaded (~100MB)
• Installed in: ~/project/venv/lib/python3.x/site-packages/

**What Will NOT Change:**
• Your Python scripts remain unchanged
• System Python is untouched

**Risk Level:** High — Installing software from internet

**If You Need to Undo:** Run `pip uninstall pandas`

Should I proceed?

User feels: "Oh, I understand. I'm in control."

---

New in v0.1.6

Automatic Status-Lite Reports

After every code change, you get a quick 3-bullet summary:

**Status-Lite:**
• **Did:** Added user authentication middleware to the Express server
• **Changed:** Created `src/auth/middleware.js` (87 lines), modified `src/server.js` (5 lines)
• **Undo:** Delete the auth directory and remove lines 23-27 from server.js

40-60 words. Automatic. Non-intrusive.

Interactive Brainstorm Mode

Turn vague ideas into developer-ready specs:

$ norm-claude brainstorm

🧠 BRAINSTORM MODE ACTIVATED

You: I want to build a tool for lawyers to track billable hours

Claude: I'll help you develop a detailed specification. Let's start:

What problem is this idea trying to solve?

You: Lawyers forget to log hours and lose billable time

Claude: Got it — time tracking for billable work.

Who are the primary users? Solo practitioners, small firms, or large firms?

[...continues one question at a time through requirements, architecture, data, testing...]

Claude: Based on our discussion, here's your developer-ready specification:

# Specification: Billable Hours Tracker

## 1. Overview
- **Problem Statement:** Lawyers lose revenue by forgetting to track billable time
- **Goals:** Auto-track time, minimize manual logging, integrate with existing tools
- **Success Criteria:** 90%+ of billable time captured automatically

[...complete 7-section spec...]

ONE question at a time. Comprehensive output. Ready to implement.

---

Installation (Mac)

Quick Install

cd ~/Documents/norm-mode/cli
./install.sh

Manual Install

# 1. Copy CLI to PATH
sudo cp ~/Documents/norm-mode/cli/norm_claude.py /usr/local/bin/norm-claude
sudo chmod +x /usr/local/bin/norm-claude

# 2. Initialize project
norm-claude init

# 3. Set environment variable (add to ~/.zshrc)
export NORM_MODE_PROMPTS="$HOME/Documents/norm-mode/prompts"

# 4. Reload shell
source ~/.zshrc

---

Usage

Launch Norm Mode

norm-claude

Launches Claude Code with Norm Mode automatically activated. Status-lite reports appear automatically after code changes.

Launch Brainstorm Mode

norm-claude brainstorm

Launches interactive brainstorming session. Claude asks ONE question at a time to help you develop a comprehensive specification for your idea. Exit anytime by saying "exit brainstorm" to get a developer-ready spec.

View STATUS Schema

norm-claude status

Prints the full STATUS report template (120-160 words, 7 sections).

View Status-Lite Schema

norm-claude status-lite

Prints the status-lite template (40-60 words, 3 bullets: Did, Changed, Undo).

View ERROR_OPINION Schema

norm-claude opinion

Prints the ERROR_OPINION template for reference.

View Help

norm-claude help

Shows the quickstart guide.

Initialize Project

norm-claude init ~/path/to/project

Creates project structure with prompts and examples.

---

In-Session Commands

While using Claude Code in Norm Mode, type these commands as plain text (no slash needed):

Note: Use plain text commands without / to avoid conflicts with Claude Code's built-in commands.

status

Get a full STATUS report (120-160 words, 7 sections) showing:

• What we just did
• What changed and what did NOT change
• Risk level
• How to undo
• Safe next actions

Use when: Confused, before risky actions, need deep-dive understanding

status-lite

Get the most recent status-lite report (if applicable). Status-lite automatically appears after material changes, but you can request it again if needed.

Use when: Want to review what just changed

brainstorm

Start a brainstorming session for an idea. Claude will ask ONE question at a time to help you develop a comprehensive specification. Say "exit brainstorm" when done to get a developer-ready spec.

Use when: Have an idea but need help turning it into an actionable plan

opinion

Get an ERROR_OPINION report that:

• Translates errors into plain language
• Explains what it does NOT mean (anxiety reduction)
• Provides Primary + Alternative fix approaches
• Normalizes the error (everyone hits this)

Use when: After seeing an error message

explain [term]

Define a technical term in plain language

Example: explain virtual environment

risk

Explain the risk level of the last action

---

How It Works

STATUS Report Schema (Fixed Format)

Every STATUS report follows this 7-section structure:

1. Current Mode (Planning | Editing | Running | Installing | Debugging | Reviewing)
2. What We Just Did (1-2 bullets in plain language)
3. What Changed (specific files/commands with inline explanations)
4. What Did NOT Change (2-3 reassurance bullets)
5. Risk Level (Low | Medium | High) + one-sentence why
6. If You Need to Undo This (1-3 concrete steps, no git assumed)
7. Safe Next Actions (3 bullets)

Target: 120-160 words (max 200)

Key rule: Always include "What did NOT change" for reassurance

---

ERROR_OPINION Schema (Fixed Format)

Every ERROR_OPINION follows this 6-section structure:

1. Issue Identification (one sentence, plain language)
2. Error Message (Verbatim) (code block)
3. Analysis
   • What this error means (plain language)
   • What likely caused this (reasoning)
   • What this does NOT mean (2-3 anxiety-dispelling bullets)
4. Recommended Course of Action
   • Primary approach (3 steps)
   • Alternative approach
5. Risk Assessment (of the fix)
6. Precedent (normalizes error: "everyone hits this")

Style: Legal-opinion language ("likely", "based on evidence", "in my professional opinion")

---

Risk Taxonomy

Low Risk (Reading, viewing, editing docs)

• Reading files
• Searching code
• Editing documentation or comments
• Running --help or --version commands

Medium Risk (Editing code, running scripts)

• Editing code files
• Running scripts or tests
• Creating new code files
• Git commits (local)

High Risk (Installing, config changes)

• Installing dependencies (pip, npm, brew)
• Editing configuration files (.env, config.yaml, package.json)
• Deleting files or folders
• Git operations that rewrite history (rebase, reset)

Before High Risk: Claude shows pre-flight warning and asks "Should I proceed?"

---

Project Structure

norm-mode/
├── README.md                          # This file
├── prompts/                           # Core prompt files
│   ├── NORM_MODE_SYSTEM_PROMPT.md     # Main system prompt (loads into Claude)
│   ├── STATUS_SNIPPET.md              # STATUS schema template
│   ├── ERROR_OPINION_SNIPPET.md       # ERROR_OPINION schema template
│   ├── QUICKSTART_FOR_LAWYERS.md      # User guide
│   └── GLOSSARY.md                    # Technical terms defined
│
├── examples/                          # Golden examples (validation)
│   ├── scenario_01_edit_prompt.md     # Low risk
│   ├── scenario_02_run_script.md      # Medium risk
│   ├── scenario_03_error_handling.md  # Error handling
│   ├── scenario_04_install_deps.md    # High risk (most critical)
│   ├── scenario_05_edit_config.md     # High risk (config)
│   ├── scenario_06_orientation.md     # User confusion
│   ├── scenario_07_git_commit.md      # Git operations
│   ├── scenario_08_new_file.md        # File creation
│   ├── scenario_09_debugging.md       # Multi-step session
│   └── scenario_10_first_setup.md     # First-time setup
│
└── cli/                               # CLI wrapper
    ├── norm_claude.py                 # Main CLI script
    ├── install.sh                     # Installation script
    └── README.md                      # CLI documentation

---

Design Principles

1. Radical Transparency

Always state what's about to happen before doing it, especially for Medium/High risk actions.

2. Consistent Reassurance

In every significant response, explicitly state what did NOT change alongside what did change.

3. No Jargon (Or Define It)

Never use technical terms without inline definitions (e.g., "pip, which is Python's package installer").

4. Recovery First

Before any Medium/High risk action, state the rollback plan. Never assume git knowledge.

5. Respect Anxiety

Treat "I'm not sure what's happening" as a valid concern requiring a full STATUS report.

---

Why Norm Mode?

Problem

Lawyers and other coding novices using Claude Code feel anxious because:

• They don't know what's happening right now
• They don't know what changed or what's about to change
• They fear "breaking their computer"
• They don't understand errors
• They can't tell if it's safe to continue

Solution

Norm Mode provides:

• Situational awareness: STATUS reports show exactly where you are
• Safety assurances: "What did NOT change" provides explicit reassurance
• Transparent risk: Every action labeled Low/Medium/High with reasoning
• Clear undo paths: Rollback steps that work without git
• Error normalization: ERROR_OPINION reports frame errors as puzzles, not failures

Result

Users feel:

• "I understand what's happening"
• "I know what changed and what's still safe"
• "I can undo this if needed"
• "Errors are normal and fixable"
• "I'm in control"

---

For Developers

Customizing Prompts

Edit files in prompts/ to adjust tone, schemas, or add new features.

Adding Golden Examples

Create new scenario files in examples/ following the existing format. Use these to validate that outputs match schemas.

Testing

Run through scenarios in examples/ manually:

1. Start Norm Mode session
2. Follow scenario context
3. Verify output matches expected STATUS or ERROR_OPINION
4. Check word count (120-160 target, 200 max)
5. Verify "What did NOT change" is present

Extending the CLI

Edit cli/norm_claude.py to add new commands or features. The CLI is a simple Python script with no external dependencies.

---

FAQ

Do I need to know git?

No. All rollback instructions work without git. Git is mentioned as an optional tool when available.

What if I don't have Claude Code installed?

Install Claude Code first, then install Norm Mode. The norm-claude command launches Claude Code, so it needs to be available.

Can I use this outside of legal work?

Yes! Norm Mode is designed for anyone who's new to programming and needs extra guidance and reassurance.

Can I use this in VS Code?

Yes. Claude Code works in VS Code terminal. Norm Mode works anywhere Claude Code works.

What if I see an error message I don't understand?

Type opinion and Claude will translate it into plain language with a fix strategy.

How do I know what changed?

Every action automatically generates a STATUS report showing what changed, what didn't, and how to undo.

Can I turn Norm Mode off?

Yes. Simply start a new Claude Code session without loading the Norm Mode system prompt.

---

Roadmap

v0.1.6 (Current)

• ✅ Prompt kit with STATUS and ERROR_OPINION schemas
• ✅ CLI wrapper for easy launching
• ✅ 10 golden example scenarios
• ✅ Quickstart guide and glossary
• ✅ Status-lite - automatic lightweight status reports (40-60 words)
• ✅ Brainstorm mode - interactive spec development with one-question-at-a-time sessions

v0.2.0 (Future)

• Session history tracking
• Enhanced pre-flight confirmations
• VS Code extension
• Test runner integration

v1.0.0 (Future)

• Multi-language support (beyond Python)
• Team templates for custom risk levels
• Integration with company wikis/docs
• Telemetry (opt-in) to improve schemas

---

Contributing

Contributions welcome! Areas where help is needed:

• More golden example scenarios (especially edge cases)
• Windows compatibility testing
• Additional technical terms for glossary
• Translations to other languages

Please open an issue or PR at: [GitHub URL]

---

License

MIT License - see LICENSE file for details

---

Support

• In-session: Type status or opinion for help
• Quickstart: Run norm-claude help
• Issues: [GitHub Issues URL]
• Questions: [Discussion Forum URL]

---

Norm Mode: Empowering lawyers to code with confidence. 🚀