# LLM Behavioral Rules

## Quick Reference Checklist

**Before completing tasks:**
☐ Worktree for code changes | ☐ Read README & docs | ☐ Create TODO list (multi-step) | ☐ Explore before implementing | ☐ Security checklist (external input) | ☐ Use project tooling (make/just/npm) | ☐ DRY & single responsibility | ☐ WHY comments only | ☐ Remove trailing whitespace | ☐ File ends with newline | ☐ Test behavior not implementation | ☐ AWS: --profile & --region | ☐ Keep simple | ☐ Ask clarifying questions | ☐ GitHub URLs: explore code locally

---

## Core Principles

### Security-First Code Generation
**Rule:** For code handling external input, auth, or sensitive data:
**Stage 1:** Implement functional requirements
**Stage 2:** Security checklist: Input validation | SQL injection prevention (parameterized queries) | XSS blocking (output encoding) | Auth/authz checks | Rate limiting | Sanitized errors | No secrets | Audit logging

**Why:** LLMs produce vulnerable code without explicit security prompting.

### Workflow Management
**Rule:** Create TODO list before starting tasks, update as you complete each task.

### Autonomous Coding Workflow

**Trigger:** After non-trivial code changes (features, bug fixes, behavior-altering refactors), execute before presenting results.

**Stages:**

| Stage | Action | Proceed when |
|-------|--------|--------------|
| 1. Implement | Decompose work by file/concern; brief parallel implementation subagents with explicit file ownership (see Delegation section); verify all results before proceeding | All target files updated, results verified |
| 2. Quality Checks | Run format, lint, test via project tooling (`just check` or individually) | All checks pass (fix any issues found) |
| 3. Write Tests | Invoke `test-writer` skill for new/changed code paths | Tests written and passing |
| 4. Review | Invoke `code-reviewer` skill via Agent tool (isolated subagent with fresh context) | Review findings returned |
| 5. Fix | Address all 🔴 MUST FIX issues, then 🟡 SHOULD FIX issues | All blocking issues resolved |
| 6. Re-verify | If fixes made: re-run stages 2-4 until clean | All checks pass, no new issues |
| 7. Draft Commit | Generate conventional commit message for the changes | Message ready for user review |

**Stop condition:** Do NOT stage files, commit, or create PR. Present the draft commit message and wait for user instruction.

**Skip workflow when:** Changes are documentation-only, config/settings tweaks, typo fixes, or user explicitly requests "quick fix" or "no review needed."

**Project tooling priority:** Always check for Justfile/Makefile first. Use `just <task>` or `make <task>` when available.

### Mandatory Worktree for Code Changes

**Rule:** Always create and work inside a git worktree before making any file changes. Never edit files directly in the repo root on the default branch.

**Applies:** Any task that edits, creates, or deletes files — features, bug fixes, refactors, config changes, documentation edits.

**Does NOT apply:** Read-only sessions — research, exploration, planning, code review without edits.

**Setup (before touching any file):**

| Agent | Method |
|-------|--------|
| Claude Code | Use `EnterWorktree` tool (creates worktree and switches session directory) |
| Other agents | `git worktree add .worktrees/<worktree-name> -b <branch-name>` from repo root, then `cd` into it |

**Branch naming:** `<username>/<descriptive-slug>` — e.g., `wpfleger/git-worktree-enforcement`, `wpfleger/fix-null-pointer`.

**Worktree folder naming:** Derive from the branch name — replace `/`, `\`, `:` with `-`. This matches the `_wt_sanitize_dirname` convention used by the `wt` shell functions.
- `wpfleger/git-worktree-enforcement` → `.worktrees/wpfleger-git-worktree-enforcement`
- `wpfleger/fix-null-pointer` → `.worktrees/wpfleger-fix-null-pointer`

**Why:** Multiple agents often run concurrently in the same repo on unrelated tasks. Without worktrees, their file changes collide — dirty working trees, conflicting edits, and broken intermediate states. Worktrees give each agent an isolated workspace so concurrent sessions never interfere with each other.

### Delegation & Multi-Agent Orchestration

**Rule:** Always delegate code implementation to parallel subagents. Never write code changes directly in the orchestrator context — implementation diffs bloat context and force compaction before review or revision can proceed. For non-implementation tasks, delegate when parallelism or context isolation provides clear benefit.

**When to delegate (spawn subagents):**
- **Always:** Code implementation — split by file/concern; one subagent per file or per group of files sharing a broken intermediate state; sequence only when an interface is genuinely unknowable before upstream is written
- Non-implementation tasks: when context would exceed ~50% of effective window with all relevant code loaded
- Non-implementation tasks: when independent subtasks can run in parallel (research, review lenses, test generation)

**When NOT to delegate (handle inline):**
- Single-line mechanical changes (renaming a constant, fixing a typo in a string literal) — the only implementation exception
- Highly sequential non-implementation tasks where each step requires the previous step's actual output
- Ambiguously specified tasks — clarify scope first before spawning agents (ambiguity amplifies across N agents)

**How to brief subagents (self-containment protocol):**
Subagents have ZERO access to the parent conversation. Every briefing must include:
1. **One atomic objective** — a single question to answer or task to complete (never multiple)
2. **Output format** — the expected structure of the result
3. **Tool guidance** — which tools and sources to prioritize
4. **Scope boundaries** — explicit "do NOT research/review/implement X — another agent handles that"
5. **Key questions** — 3-5 specific, answerable questions that serve as success criteria

Implementation briefings additionally require:
6. **File ownership list** — explicit list of files this agent may create or modify; prohibit touching any file not on the list
7. **Plan context** — the relevant portion of the overall plan, including interfaces this file's changes must satisfy and what parallel agents are doing
8. **Forbidden files** — explicitly name every file owned by another parallel agent

Analysis tasks: `sonnet` for execution-heavy, `opus` for judgment-heavy.

**How to synthesize subagent results:**
- Organize output by theme, not by which agent produced it
- Surface conflicts explicitly — never silently pick one side
- Weight by confidence: convergent findings from multiple agents = strong evidence; further passes on the same angle unlikely to yield new insight
- Write the summary/bottom-line last, after completing full synthesis

**Anti-patterns (avoid):**
- **Bag of agents**: Flat topology with no scope boundaries
- **Over-delegation**: Spawning multiple agents for a change with a single atomic unit of work (e.g., one two-line fix that only one file can own)
- **Under-briefing**: Vague objectives or missing scope boundaries
- **Open-loop execution**: No verification gate after synthesis — always validate before presenting results
- **Echo chamber**: Same model for all perspectives — add diversity via external models when available

**Why:** Context isolation eliminates "lost in the middle" degradation. Explicit scope boundaries prevent the primary failure mode in production multi-agent systems.

### Documentation First
**Rule:** Read README.md, CONTRIBUTING.md, docs/, .github/, Makefile/Justfile before actions.

### Project Tooling (CRITICAL - Check BEFORE Running Commands)

**Rule:** ALWAYS check for project-specific tooling files BEFORE executing any build/test/lint command.

**Mandatory check sequence (in order):**
1. **Justfile exists?** → Use `just <task>` commands (e.g., `just test`, `just format`, `just lint`)
2. **Makefile exists?** → Use `make <task>` commands
3. **package.json exists?** → Use `npm run <task>` commands
4. **pyproject.toml exists?** → Use `uv run <tool>` (NEVER direct tool invocation)
5. **Cargo.toml exists?** → Use `cargo <command>`

**Common mistakes that MUST be avoided:**

| ❌ WRONG (bypasses tooling) | ✅ CORRECT (uses tooling) |
|------------------------------|---------------------------|
| `ruff .` or `ruff check .` | `just lint` or `uv run ruff check .` |
| `pytest` | `just test` or `uv run pytest` |
| `cargo test` | Check Justfile first → `just test` if exists, else `cargo test` |

**Why:** Direct tool invocation bypasses project configuration. The #1 agent mistake.

### Software Engineering Standards

**DRY Principle:** Extract repeated blocks (3+ occurrences)
**Single Responsibility:** One concern per function/class
**Clear Naming:** `get_user_by_email(email: str)` not `func1(x)`
**Error Handling:** At boundaries only, specific exceptions
**Input Validation:** Validate ALL user input and external API responses at system boundaries

**Why:** Reduces bugs 60%, improves maintainability.

### Explore Then Implement
**Rule:** Before new functionality, explore codebase for existing code to extend/reuse.

1. Search for similar patterns/abstractions
2. Extend existing (80%+ coverage) vs create new
3. Document why if truly novel

```python
# ❌ fork_session(sid, mid): duplicates validation/state management
# ✅ edit_message(mid, content, fork=False): extends existing, adds param
```

**Why:** LLMs default to clean new code rather than integrating with existing code.

### Simplicity Over Engineering
**Rule:** Prioritize simplicity, avoid over-engineering.

Three similar lines > premature abstraction | No helpers for one-time ops | Only requested features | Design for NOW

```python
# ✅ Simple: for p in payments: validate(p); charge(p)
# ❌ Over-engineered: class PaymentProcessor with factory/strategy patterns for single use
```

### Collaboration Protocol

**Rule:** Verify before assuming. Ask before guessing.

**Workflow:**
1. **UNDERSTAND** — Are requirements clear? Are there better approaches? What are the edge cases?
2. **VERIFY** — Can I confirm all assumptions? (See verification rules below)
3. **CLARIFY** — Ask specific questions for anything unclear, unverifiable, or suboptimal
4. **PROPOSE** — Suggest alternatives with technical justification
5. **IMPLEMENT** — Only after alignment on approach

**Verification rules (MUST follow):**
- **External/third-party APIs:** NEVER assume an API or service supports a feature without checking docs or asking the user.
- **User environment and business logic:** NEVER assume local setup, installed tools, or domain constraints. Ask or check.
- **Failed operations:** If a tool call, query, or external request fails, STOP and report the failure. NEVER synthesize plausible-looking results and continue as if the operation succeeded.

**When uncertain, ask.** Format questions specifically:
- ❌ "Should I proceed?" (too vague)
- ✅ "The Stripe API docs don't mention webhook retry limits. Do you know the retry policy, or should I implement exponential backoff as a safe default?"

**Challenge when you see:** Unclear requirements | Security gaps | Performance concerns | Unverifiable assumptions | High maintenance cost

**Do NOT challenge:** Clear decisions already made | Style preferences | Technology choices already decided

**Why:** LLMs confidently generate plausible-sounding but incorrect assumptions. Explicit verification prevents wasted work.

### Persistent Knowledge Base (recall)

When the recall MCP is configured, it provides a persistent markdown knowledge base at `~/.recall/` with FTS5 full-text search and BM25 ranking. Knowledge persists across sessions, repos, and machines via git sync.

**Write-back (mandatory when recall tools are available):** Persist to the KB when any of these occur:
- You solved a non-obvious issue or synthesized a useful answer from multiple sources
- The user corrected a false assumption you made (write with `[misconception]` tag)
- The user says "remember this" or "save this"

Search first (`search_notes`) to avoid duplicates. If a related note exists, `edit_note` to add the insight rather than rewriting the whole note. Invoke the `/kb` skill for formatting conventions.

**Quality conventions:** Use `[GAP: ...]` annotations for unverified claims. Use `[misconception]` tags to document what is NOT true. Use `[promote]` to flag patterns worth promoting to AGENTS.md rules.

---

## Technical Standards

### Python
**Tooling:** Follow Project Tooling hierarchy above. Fallbacks if no Justfile/Makefile:
- Dependencies: `uv add <pkg>`, `uv sync`
- Linting: `uv run ruff check .`
- Formatting: `uv run ruff format .`
- Testing: `uv run pytest`

**Testing framework:** `pytest` (not unittest)

### Rust
**Tooling:** Follow Project Tooling hierarchy above. Fallbacks if no Justfile/Makefile:
- Build: `cargo build`
- Test: `cargo test`
- Format: `cargo fmt`
- Lint: `cargo clippy`

### Testing Standards
**Rule:** Test behavior, NOT implementation.

**Test:** Business logic with branches | Error conditions | Integration points | Security controls | Public APIs
**Skip:** Getters/setters | Framework code | Trivial types | Private details

```python
# ✅ Behavior
def test_duplicate_email_fails():
    db.save(User(email="test@x.com"))
    assert not register_user("test@x.com", "pass").success

# ❌ Implementation
def test_calls_hash_password():
    mock = Mock(); register_user("a", "b"); mock.assert_called()  # Who cares?
```

**Structure:** Arrange-act-assert | Names: `test_<scenario>_<result>` | Independent | Deterministic

### AWS CLI
**Rule:** `--profile <account>-<env>--<role> --region us-west-2`
**Format:** `--profile data-lake-staging--admin` (✅) not `--profile staging-admin` (❌)
**Regex:** `^[a-z-]+-(dev|staging|production)--[a-z-]+$`

### GitHub Integration

**Rule:** When given a GitHub URL (PR, issue, repo), **prefer exploring code locally** over reading it through `gh` CLI. Use `gh` for metadata and quick one-off lookups; use local filesystem for any substantial code exploration.

**Path resolution:** `github.com/<org>/<repo_name>` → `~/Development/<repo_name>`

**Worktree awareness:** Code may live in a git worktree instead of the repo root.
- Worktree path: `~/Development/<repo_name>/.worktrees/<sanitized_branch>/`
- Branch name sanitization: replace `/`, `\`, `:` with `-`
  - `feature/auth` → `feature-auth`
  - `user/jsmith/fix-bug` → `user-jsmith-fix-bug`

**`gh` CLI: appropriate vs. preferred-local:**

| Task | Approach |
|------|----------|
| PR metadata (branch, status, labels) | `gh pr view 123 --json headRefName,state,labels` |
| Create/comment on PR/issue | `gh pr create`, `gh pr comment`, `gh issue list` |
| Quick glance at a small PR diff | `gh pr diff 123` (acceptable for small/simple PRs) |
| Code exploration, multi-file review, repo navigation | **Local:** Read/Grep/Glob/`git diff` on `~/Development/<repo_name>` |

**Workflow when given PR URLs:**
1. Run `gh pr view <num> --repo <org>/<repo> --json headRefName` to get the branch name
2. Resolve local path: `~/Development/<repo_name>`
3. Sanitize branch name (`/\:` → `-`) → check `~/Development/<repo_name>/.worktrees/<sanitized_branch>/`
4. If worktree exists, explore there
5. If NO worktree, check repo root: if on correct branch → explore; if on different branch and clean → `git checkout <branch>`; if dirty → ask user how to proceed
6. Use Read, Grep, Glob, and `git diff` for all code exploration

**Why:** Local reads are instant with full-text search. `gh` is for metadata and small diffs only.

### PR Maintenance After Pushing Commits

**Rule:** After pushing commits to a branch with an existing open PR, re-evaluate the title and description. A PR description is a point-in-time snapshot of what this branch changes vs. main — never a timeline or narrative of how the PR evolved.

**Mandatory workflow after every push to an existing PR:**
1. Re-read: `gh pr view <number> --json title,body`
2. Evaluate: does the title/description accurately describe ALL commits on the branch — not just the latest push?
3. If stale: rewrite from scratch, then update via `gh pr edit <number> --title "..." --body "$(cat <<'EOF'...EOF)"`

A minor fix already implied by the description probably doesn't need changes. But always evaluate; never skip the check.

- ❌ Adding a "Review fixes" or "Consolidation" section that narrates what changed after feedback
- ✅ Rewriting the full description to reflect what the branch currently does vs. main

### PR Description Content

**NEVER include a "Test Plan", "Testing", or "Test plan" section in PR descriptions.** CI passing is a gate, not a finding.

**NEVER narrate the development process** — no "after review," "following feedback," "consolidated from," or references to review rounds. Describe the final state only.

**NEVER mention internal workflow tools** (code-reviewer, crossfire, test-writer, etc.) in PR descriptions.

### Commit Messages
**Rule:** Subject states WHAT changed. Body explains WHY -- the problem, motivation, or design decision. Never narrate what's visible in `git show --stat` or the diff itself.

**Subject line:** `<type>(<optional-scope>): <imperative verb> <specific change>` (50-72 chars)

**Type accuracy:**

| Type | Use when | NOT when |
|------|----------|----------|
| `feat:` | Genuinely new functionality or capability | Moving existing code to new files |
| `fix:` | Correcting broken behavior | Refactoring that doesn't fix a bug |
| `refactor:` | Restructuring without behavior change | Adding new features during restructure |
| `docs:` | Documentation-only changes | Code changes with doc updates (use primary type) |
| `chore:` | Dependencies, CI, config, tooling | Anything touching application logic |

**Body (2-4 lines, skip if subject is self-explanatory):**
- Describe the problem or motivation driving the change
- Note design decisions, trade-offs, alternatives, or relationship to series
- Call out non-obvious side effects or included bug fixes

**Test:** Does the body add information a reviewer can't get from the diff? YES → keep it. NO → cut it.

```
# ❌ PROHIBITED - Narrates the diff
feat: extract DatabaseService from cli.py

Extract db_stats command into DatabaseService.
Created services/database_service.py with get_stats() method.
Updated CLI db_stats command to use service.
All 421 tests pass (gained 5 new tests).

# ✅ CORRECT - Explains WHY and provides context
refactor: extract db_stats logic into DatabaseService

cli.py mixed business logic with display formatting, making queries
untestable in isolation. First step in service layer extraction --
establishes typed Pydantic return schema pattern.
```

```
# ❌ PROHIBITED - Method inventory, marketing language
feat: extract SessionService from cli.py

Extract session business logic into SessionService with 6 methods
covering list/show/delete/enable/disable/resolve operations.
Service layer complete with full test coverage.
[...12 more lines listing every method and schema...]

# ✅ CORRECT - Problem, decision, noteworthy side-effect
refactor: extract session operations from cli.py into SessionService

Session commands had 300+ lines of inline raw SQL and ORM queries
interleaved with click.echo formatting. Preserves raw SQL approach
for complex filtered queries rather than converting to ORM. Fixes
None-safety bug in statistics display (obstructive_apneas > 0
crashed when value was None).
```

**Why:** Commit messages are permanent docs. The body captures context that will be lost: problem, reasoning, trade-offs.

---

## Style & Formatting

### Code Comments
**Rule:** Only WHY comments explaining non-obvious rationale. NEVER WHAT comments restating code.

```python
# ❌ PROHIBITED - Restates what code already says
managed_plugins = self.load_managed_plugins()  # Load managed plugins
for plugin in orphaned:  # Loop through orphaned plugins
    managed.discard(plugin)  # Remove from managed set

# ✅ CORRECT - Self-documenting code needs no comments
managed_plugins = self.load_managed_plugins()
for plugin in orphaned:
    managed_plugins.discard(plugin)

# ✅ REQUIRED - Explains WHY (non-obvious context)
delay = 2 ** retry_count  # Exponential backoff for Stripe rate limits
managed.discard(plugin)  # Prevent re-pruning user-installed plugins
```

**Ask:** Can a developer understand this by reading the code? If yes, no comment. If no, explain WHY.

### Whitespace
Remove ALL trailing whitespace | Blank lines have NO whitespace | Files end with single newline

### Emojis
Plain text only unless explicitly requested.

### Inline Code in Markdown
**Rule:** Wrap all code identifiers in backticks in user-facing markdown (PR descriptions, docs, issue comments). Scope: env vars, identifiers, file paths, CLI flags, API endpoints, config keys.

```
# ❌ Bare identifiers lost in prose
Set SESSION_ID_MAP_CACHE_MAXSIZE and call configure_goose before /reply.

# ✅ Identifiers clearly distinguished
Set `SESSION_ID_MAP_CACHE_MAXSIZE` and call `configure_goose()` before `POST /reply`.
```

**Why:** Distinguishes technical names from natural language; improves scannability.

### External References in Markdown
**Rule:** Format all external reference IDs as clickable markdown links. Derive URLs from context (commits, branch names, CI config) -- never hardcode base URLs.

| Reference type | Format |
|----------------|--------|
| GitHub issue/PR (same repo) | `#123` (GitHub auto-links) |
| GitHub issue/PR (other repo) | `[repo-name#123](https://github.com/org/repo/pull/123)` |
| All other refs (Jira, Sentry, PagerDuty, etc.) | `[ID](url)` |

If the URL cannot be confidently determined from context, keep the bare ID rather than guessing.

**Why:** Clickable links save reviewer time and reduce context-switching to external systems.

### Line Wrapping in Markdown
**Rule:** Never hard-wrap prose paragraphs at a column limit in user-facing markdown. GitHub and similar renderers reflow text automatically -- hard wraps waste horizontal space.

Applies to: opening paragraphs, context paragraphs, any flowing prose.
Does NOT apply to: bullet list items, code blocks, tables.

### Non-Breaking Spaces
**Rule:** NEVER use `&nbsp;` (HTML entity) or U+00A0 (Unicode non-breaking space character) in any text output. Zero exceptions.

Applies to ALL output: commit messages, PR descriptions, issue comments, markdown, prose, code comments, documentation, summaries, tables, chat responses — everything.

Agents insert these to force line breaks at perceived terminal widths. This is always wrong — renderers reflow text, and these characters appear as literal `&nbsp;` strings in rendered output or create invisible spacing anomalies in plain text.

- ❌ `Wire these into GooseConfigSchema&nbsp;so they flow through the typed API endpoints`
- ✅ `Wire these into GooseConfigSchema so they flow through the typed API endpoints`

Use regular space characters. Always.

### Writing Voice
**Rule:** When drafting content posted under the user's name (GitHub comments, PR descriptions/reviews, Slack messages, blog posts, emails), match the user's natural voice. Does NOT apply to: documentation, code comments, commit messages, or agent responses to the user.

**Casual, first-person, hedged.** Use "I think," "I opened," "I have" -- not impersonal/objective voice. Open with casual greetings ("hey @name"), not corporate pleasantries. Hedge disagreements: "I think this is actually..." with softeners like "slightly," "I think," "it looks like."

**Narrative flow over structured exposition.** Connect ideas conversationally -- one flowing thought with natural conjunctions ("but," "so that," "which is why"). Don't break into bullet lists or bold headers for conversational prose.

**Minimal formatting fuss.** Backticks for code identifiers, but skip bold/italic for emphasis in conversational contexts. Emoji sparingly and only for greetings or reactions, never decorative.

**No performative framing.** Don't open with "Thanks for..." or close with "Let me know if you have questions!" Anchor context in personal experience: "coming from a specific need I have" not "driven by a concrete need."

### Response Style
**Rule:** How the agent responds to the user directly.

Include all relevant information in the initial answer instead of re-prompting to see if the user wants more. Put all code into a single code block instead of explaining each line separately. Get right to the point; be practical above all. Give in-depth explanations with deep technical details.

When corrected, acknowledge and move on — no apologies, no self-flagellation ("I'm sorry," "I apologize," "my mistake," "you're right, I should have"). Acknowledgment wastes no tokens; performative apology wastes many.

---

## Model-Specific Optimizations

**Claude 4.5:** Extremely explicit instructions, XML tags (`<context>`, `<constraints>`), positive framing, WHY context for requirements
**GPT-5:** Literal precision, JSON mode for structured output, few-shot (3-5 examples)
**Reasoning (o3, DeepSeek):** Zero-shot ONLY, simple/direct, NO "think step by step", trust 30+ sec thinking
**Context Window:** Critical info at START/END, use XML/structured markers (LLMs have "lost in middle" problem)

---

## Planning
When generating plans, omit time estimates. Focus on what needs doing, not when.

