norm-claude 0.1.6

Situational awareness layer for Claude Code, 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:

• Clear STATUS reports after every action (what changed, what didn't, how to undo)
• Fixed schemas for consistency (120-160 word reports, always same structure)
• 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."

---

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

This launches Claude Code and shows you the system prompt to paste. Claude will then operate in Norm Mode for the session.

View STATUS Schema

norm-claude status

Prints the STATUS report template for reference.

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 STATUS report 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, or anytime

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.0 (Current)

• Prompt kit with STATUS and ERROR_OPINION schemas
• CLI wrapper for easy launching
• 10 golden example scenarios
• Quickstart guide and glossary

v0.2.0 (Future)

• Automatic STATUS reports (no paste required)
• Interactive pre-flight confirmations
• Session history tracking
• VS Code extension

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. 🚀