# 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:

```bash
$ 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
```bash
cd ~/Documents/norm-mode/cli
./install.sh
```

### Manual Install
```bash
# 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
```bash
norm-claude
```

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

### Launch Brainstorm Mode
```bash
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
```bash
norm-claude status
```

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

### View Status-Lite Schema
```bash
norm-claude status-lite
```

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

### View ERROR_OPINION Schema
```bash
norm-claude opinion
```

Prints the ERROR_OPINION template for reference.

### View Help
```bash
norm-claude help
```

Shows the quickstart guide.

### Initialize Project
```bash
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.** 🚀
