@hopla/claude-setup 1.10.2 → 1.11.1

package/{files/commands → commands}/hopla-plan-feature.md

@@ -3,6 +3,8 @@ description: Research the codebase and create a structured implementation plan f
 argument-hint: "<feature-name-or-description>"
 ---
 
+> 💡 **Tip**: Activate Plan Mode (`Shift+Tab` twice) before running this command for deeper codebase exploration. For complex features, use Extended Thinking for better reasoning.
+
 > 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
 
 Transform the requirements discussed in this conversation into a structured plan that another agent can execute without access to this conversation.

package/commands/hopla-rca.md

@@ -0,0 +1,64 @@
+# Root Cause Analysis
+
+> Investigate a bug or issue and produce a structured RCA document.
+
+> 💡 **Tip**: Use Extended Thinking mode for complex bugs with multiple possible causes.
+
+## Input
+- `$ARGUMENTS`: Issue description, error message, or GitHub issue ID/URL
+
+## Process
+
+### Step 1: Gather Information
+- If a GitHub issue: read the full issue, comments, and any linked PRs
+- If an error: read the full error message and stack trace
+- Run `git log --oneline -20` to check recent changes
+- Run `git diff` to see current uncommitted changes
+
+### Step 2: Investigate
+- Search the codebase for the affected code: `grep`, `glob`, `read`
+- Identify the function/component where the error originates
+- Check git blame for recent changes to that area
+- Look for related tests — do they pass? Are they missing?
+
+### Step 3: Root Cause Analysis
+Apply the hopla-debug methodology:
+1. **Reproduce**: Can you trigger the issue?
+2. **Narrow**: Which exact file and line?
+3. **Hypothesize**: What's the most likely cause based on evidence?
+4. **Verify**: Can you confirm the hypothesis?
+
+### Step 4: Generate RCA Document
+Save to `.agents/rca/[issue-name].md`:
+
+```
+# RCA: [Issue Title]
+
+## Symptoms
+What the user sees / what the error is
+
+## Root Cause
+What's actually wrong and why
+
+## Evidence
+- [file:line] — what you found
+- [git commit] — what changed
+
+## Proposed Fix
+What needs to change to resolve this
+
+## Tests Needed
+- Test to reproduce the bug
+- Test to verify the fix
+
+## Prevention
+How to prevent similar issues in the future
+
+## Next Steps
+- [ ] Implement fix (run `/hopla-execute` with a plan, or fix directly if simple)
+- [ ] Add regression test
+- [ ] Validate with `/hopla-validate`
+```
+
+## Output
+The RCA document in `.agents/rca/`, ready for review or execution.

package/{files/commands → commands}/hopla-validate.md

@@ -64,6 +64,11 @@ If everything passes, confirm the project is healthy.
 
 If anything failed and could not be fixed, list the remaining issues and suggest next steps.
 
+## After Validation Passes
+
+- Suggest running `/hopla-code-review` if not already done
+- Remind that completion claims must be backed by this fresh validation evidence (see hopla-verify skill)
+
 ## Next Step
 
 After validation passes, suggest:

package/{files/CLAUDE.md → global-rules.md}

@@ -87,3 +87,48 @@ Explain in plain language when suggesting a commit, adapting to the user's langu
 - Write tests alongside implementation, not after
 - Flag security issues immediately — never leave them for later
 - If the same validation failure repeats, signal it as a system improvement opportunity
+
+---
+
+## 📋 Context Management
+
+### Three levels of CLAUDE.md
+- **Machine-level** (`~/.claude/CLAUDE.md`): These global rules — apply to all projects
+- **Project-level** (`CLAUDE.md` at repo root): Shared with team via git — project-specific rules
+- **Local-level** (`CLAUDE.local.md`): Personal overrides — NOT committed to git
+
+### Context control
+- Use `@filename` to include specific files in context (works in chat and inside CLAUDE.md)
+- Use `/compact` between related tasks (preserves learned knowledge)
+- Use `/clear` between unrelated tasks (full reset)
+- Use `#` memory mode to quickly add rules: `# Never use console.log for debugging`
+- Use `Escape` to interrupt + `#` to prevent repeated errors
+- Use `Shift+Tab` twice to activate Plan Mode for complex multi-file changes
+
+---
+
+## 🔌 MCP Servers
+<!-- List your configured MCP servers here so the agent knows what tools are available -->
+<!-- Example: -->
+<!-- - Playwright: Browser automation for E2E testing -->
+<!-- - Supabase: Database management -->
+<!-- When planning features, explicitly include MCP integration points in the plan -->
+
+---
+
+## 🛠️ Available HOPLA Commands
+When a skill applies to your current task, you MUST use it. Check available skills before responding.
+
+### Workflow: Plan → Implement → Validate
+1. `/hopla-plan-feature` — Research codebase and create implementation plan
+2. `/hopla-review-plan` — Review plan before execution
+3. `/hopla-execute` — Execute plan with validation
+4. `/hopla-validate` — Run full validation pyramid
+5. `/hopla-git-commit` — Create conventional commit
+6. `/hopla-git-pr` — Create GitHub PR
+
+### Other commands
+- `/hopla-create-prd` — Create or update Product Requirements Document
+- `/hopla-init-project` — Initialize project with CLAUDE.md and .agents/ structure
+- `/hopla-code-review-fix` — Fix issues from code review report
+- `/hopla-system-review` — Analyze plan vs execution for process improvements

package/hooks/hooks.json

@@ -0,0 +1,40 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/tsc-check.js\"",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Read|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/env-protect.js\"",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-prime.js\"",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/{files/hooks → hooks}/session-prime.js

@@ -40,6 +40,19 @@ async function main() {
         lines.push(`Project rules (CLAUDE.md excerpt):\n${content}`);
     }
 
+    // Available skills reminder
+    lines.push(`📦 HOPLA Skills Available:
+- hopla-prime: Project orientation (trigger: "orient", "get context", "load project")
+- hopla-git: Git operations (trigger: "commit", "PR", "push")
+- hopla-code-review: Code review (trigger: "review code", "code review")
+- hopla-execution-report: Post-implementation docs (trigger: "generate report")
+- hopla-verify: Completion verification (trigger: any "done"/"listo"/"finished" claim)
+- hopla-brainstorm: Design exploration (trigger: "new feature", "brainstorm", "explore options")
+- hopla-debug: Systematic debugging (trigger: "bug", "error", "debug")
+- hopla-tdd: Test-driven development (trigger: implementing with tests)
+
+⚠️ If a skill applies to the current task, you MUST use it.`);
+
     if (lines.length > 0) {
         process.stdout.write(lines.join("\n\n"));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hopla/claude-setup",
-  "version": "1.10.2",
+  "version": "1.11.1",
   "description": "Hopla team agentic coding system for Claude Code",
   "type": "module",
   "bin": {
@@ -9,7 +9,12 @@
   },
   "files": [
     "cli.js",
-    "files/"
+    "global-rules.md",
+    "commands/",
+    "skills/",
+    "agents/",
+    "hooks/",
+    ".claude-plugin/"
   ],
   "engines": {
     "node": ">=18"

package/skills/hopla-brainstorm/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: hopla-brainstorm
+description: "Design exploration and brainstorming before planning. Use when the user wants to explore options for a new feature, discuss approaches, design a solution, brainstorm ideas, or evaluate trade-offs. Trigger on: 'new feature', 'brainstorm', 'explore options', 'design', 'how should we', 'what approach', 'trade-offs', 'quiero agregar', 'diseñar', 'explorar opciones'. Do NOT use when the user already has a clear plan or is asking to execute existing work."
+---
+
+# Brainstorming: Design Exploration Before Planning
+
+## Purpose
+Explore the problem space and arrive at a validated design BEFORE creating an implementation plan. Bad planning direction = wasted plans.
+
+## Hard Gate
+**Never jump to planning or implementation before the user has approved a design approach.**
+
+## Process
+
+### Step 1: Explore Context
+- Read the project's CLAUDE.md, README, and relevant source files
+- Understand the existing architecture, patterns, and conventions
+- Identify what already exists that relates to this feature
+- Check `.agents/plans/` for any related previous work
+
+### Step 2: Ask Clarifying Questions
+Ask questions **one at a time** (don't overwhelm with a list):
+- What problem are we solving? Who benefits?
+- What does success look like?
+- Are there constraints (performance, timeline, tech stack)?
+- Are there existing patterns in the codebase we should follow or break from?
+
+Wait for the user's answer before asking the next question.
+
+### Step 3: Propose Approaches
+Present **2-3 approaches** with clear trade-offs:
+
+For each approach:
+- **Name**: A short descriptive name
+- **How it works**: 2-3 sentences
+- **Pros**: What's good about this approach
+- **Cons**: What's risky or complex
+- **Effort estimate**: Low / Medium / High
+- **Best when**: Under what conditions this is the right choice
+
+### Step 4: Design the Chosen Approach
+Once the user selects an approach:
+- Detail the implementation at a conceptual level (not code)
+- Identify files that will be created or modified
+- Map data flow and component interactions
+- Call out edge cases and potential gotchas
+- If helpful, offer a visual companion (ASCII diagram, flow chart)
+
+### Step 5: Write Design Document
+Save to `.agents/specs/YYYY-MM-DD-<topic>.md` with:
+```
+# Design: [Feature Name]
+
+## Problem
+What we're solving and why
+
+## Chosen Approach
+Which approach and why
+
+## Design
+Conceptual design details
+
+## Files Affected
+- List of files to create/modify
+
+## Edge Cases & Risks
+- Known edge cases
+- Risk areas
+
+## Open Questions
+- Anything still unclear
+
+## Next Step
+Run `/hopla-plan-feature` to create the implementation plan from this design
+```
+
+### Step 6: Review Loop
+Present the design document for user review.
+- Accept feedback using the `<? ... >` comment syntax
+- Iterate until the user approves
+- Only then suggest: "Design approved! Ready to create the plan with `/hopla-plan-feature`?"
+
+## Rules
+- Never skip to planning without design approval
+- One question at a time — don't overwhelm
+- Always ground proposals in the existing codebase (not abstract theory)
+- If the feature is trivial (< 30 minutes of work), skip the full process — just confirm approach and proceed
+- In planning mode (non-technical users): focus on product decisions, not technical details

package/{files/skills → skills}/hopla-code-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: hopla-code-review
-description: Performs a technical code review on recently changed files. Use when the user says "review the code", "code review", "check my code", "look for issues", or asks for feedback on their implementation.
+description: "Technical code review on changed files. Use when the user says 'review code', 'code review', 'check my code', 'review changes', 'look for bugs', or 'audit code'. Also use after completing implementation when validation passes. Do NOT use for reviewing plans or documents — only code."
+allowed-tools: Read, Grep, Glob, Bash
 ---
 
 > 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.

package/skills/hopla-debug/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: hopla-debug
+description: "Systematic debugging methodology for finding and fixing bugs. Use when encountering errors, bugs, failures, unexpected behavior, or when the user says 'bug', 'error', 'not working', 'failing', 'debug', 'fix', 'broken', 'falla', 'no funciona', 'error'. Do NOT use for planned feature work or refactoring — only for diagnosing and fixing unexpected problems."
+---
+
+# Systematic Debugging
+
+## Core Principle
+**ALWAYS find the root cause before proposing fixes.** Never guess at solutions.
+
+## Phase 1: Root Cause Investigation
+
+1. **Read the full error** — Don't skim. Read every line of the error message, stack trace, and logs
+2. **Reproduce** — Can you trigger the error reliably? What are the exact steps?
+3. **Check recent changes** — `git log --oneline -10` and `git diff` — did something change recently?
+4. **Gather evidence** — What do logs, test output, and error messages tell you?
+5. **Narrow the scope** — Which file, function, or line is the actual source?
+
+## Phase 2: Pattern Analysis
+
+1. **Find working examples** — Does similar code work elsewhere in the codebase?
+2. **Compare** — What's different between working and broken code?
+3. **Identify the pattern** — Is this a known pattern (race condition, stale closure, off-by-one, null reference)?
+4. **Check dependencies** — Are versions correct? APIs changed?
+
+## Phase 3: Hypothesis and Testing
+
+1. **Form ONE hypothesis** — "The bug is caused by X because of evidence Y"
+2. **Test minimally** — Make the smallest possible change to validate the hypothesis
+3. **Verify** — Did the test confirm or refute the hypothesis?
+4. **If refuted** — Go back to Phase 1 with new information, don't try another random fix
+
+## Phase 4: Implementation
+
+1. **Write a failing test** — Create a test that reproduces the bug
+2. **Implement the fix** — One fix only. Don't fix other things at the same time
+3. **Verify the test passes** — The reproduction test should now be green
+4. **Run full test suite** — Ensure no regressions
+5. **Document** — Brief comment or commit message explaining the root cause
+
+## The 3-Strike Rule
+
+**If 3 fixes fail, STOP.**
+
+After 3 failed attempts:
+- The problem is likely architectural, not a simple bug
+- Present findings to the user: "I've tried X, Y, Z. None worked because..."
+- Ask: "Should we reconsider the approach, or do you have additional context?"
+- Do NOT try a 4th random fix
+
+## Red Flags (You're Doing It Wrong If...)
+
+- You're proposing a fix before reading the full error
+- You've tried 3+ things without stopping to reassess
+- You're changing code you don't understand
+- You're fixing symptoms instead of causes
+- You're adding workarounds instead of addressing the root issue
+- You say "let me try this" without explaining WHY it should work
+
+## For Multi-Component Systems
+
+When the bug spans multiple components (frontend ↔ backend ↔ database):
+1. Add diagnostic logging at each component boundary
+2. Trace the data flow: What goes in? What comes out? Where does it break?
+3. Isolate: Can you reproduce with just one component?
+
+## Output
+
+When the bug is fixed, briefly report:
+- **Root cause**: What was actually wrong
+- **Fix**: What was changed and why
+- **Test**: What test verifies the fix
+- **Prevention**: How to prevent similar bugs (if applicable)

package/{files/skills → skills}/hopla-execution-report/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: hopla-execution-report
-description: Generates an implementation report documenting what was built. Use when the user says "generate the report", "genera el reporte", "documenta lo implementado", "execution report", "document what was done", "write the implementation report", or after finishing a feature before committing.
+description: "Post-implementation documentation generator. Use when the user says 'generate report', 'document what was done', 'execution report', 'what changed', or after a feature implementation is complete and validated. Do NOT use during implementation — only after completion."
+allowed-tools: Read, Grep, Glob, Bash
+model: sonnet
 ---
 
 > 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.

package/{files/skills → skills}/hopla-git/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hopla-git
-description: Handles git operations: creating commits, making pull requests, pushing branches. Use when the user asks to commit, create a commit, save changes to git, make a PR, create a pull request, push the branch, or any git workflow action.
+description: "Git operations handler for commits and pull requests. Use when the user mentions 'commit', 'save changes', 'create commit', 'PR', 'pull request', 'push', 'merge request', or any git workflow action. Do NOT use for git status checks or branch management — only for commits and PRs."
 ---
 
 > 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.

package/skills/hopla-parallel-dispatch/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: hopla-parallel-dispatch
+description: "Parallel agent dispatch for independent tasks. Use when 2+ tasks have no shared state and can run simultaneously, during brainstorming to explore multiple approaches, or when the user says 'in parallel', 'simultaneously', 'at the same time'. Do NOT use when tasks have dependencies or share state."
+---
+
+# Parallel Agent Dispatch
+
+## When to Parallelize
+
+**Good candidates:**
+- Researching multiple approaches during brainstorming
+- Reviewing independent modules simultaneously
+- Running tests on separate features
+- Investigating different parts of the codebase
+- Implementing truly independent vertical slices
+
+**Never parallelize:**
+- Tasks that modify the same files
+- Tasks with data dependencies (Task B needs Task A's output)
+- Tasks that share database state
+- Tasks where order matters
+
+## How to Dispatch
+
+### Step 1: Identify Independent Tasks
+From the current work, identify tasks that:
+- Don't share files
+- Don't share state
+- Can succeed or fail independently
+- Have clear, isolated scope
+
+### Step 2: Create Agent Prompts
+For each parallel task, define:
+- **Scope**: Exactly what this agent should do (and NOT do)
+- **Goal**: Clear success criteria
+- **Constraints**: Files it can touch, patterns to follow
+- **Expected output**: What to report back
+
+### Step 3: Launch in Parallel
+Use the Agent tool with multiple invocations in a single message.
+
+### Step 4: Collect and Merge
+- Wait for all agents to complete
+- Review each agent's output
+- Resolve any unexpected overlaps
+- Validate the combined result
+
+## Common Parallel Patterns
+
+### Brainstorming (3 approaches)
+```
+Agent 1: "Research approach A for [feature]. Pros, cons, effort estimate."
+Agent 2: "Research approach B for [feature]. Pros, cons, effort estimate."
+Agent 3: "Research approach C for [feature]. Pros, cons, effort estimate."
+```
+
+### Code Review (by module)
+```
+Agent 1: "Review changes in src/auth/ for bugs and security issues"
+Agent 2: "Review changes in src/api/ for bugs and performance issues"
+Agent 3: "Review changes in src/ui/ for accessibility and UX issues"
+```
+
+### Research (multiple areas)
+```
+Agent 1: "Find all usages of [function] across the codebase"
+Agent 2: "Research how [library] handles [pattern] in their docs"
+Agent 3: "Check if similar functionality exists in our codebase"
+```

package/{files/skills → skills}/hopla-prime/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: hopla-prime
-description: Orients Claude in a project at the start of a session. Use when the user says "orient yourself", "get oriented", "prime yourself", "what is this project", "load context", or asks Claude to familiarize itself with the codebase before starting work.
+description: "Project orientation and context loading. Use when starting a session, onboarding to a project, needing to understand the codebase, or when the user says 'orient', 'get context', 'load project', 'what is this project', 'prime', or 'start'. Do NOT use mid-task when the project is already understood."
+allowed-tools: Read, Grep, Glob, Bash
+model: sonnet
 ---
 
 > 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.

package/skills/hopla-subagent-execution/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: hopla-subagent-execution
+description: "Subagent-driven execution for large plans. Use when executing plans with 5+ tasks to maintain context quality, when the user says 'use subagents', 'parallel execution', or when context degradation is a concern in long implementations. Do NOT use for small plans (< 5 tasks) or quick fixes."
+---
+
+# Subagent-Driven Execution
+
+## When to Use
+- Plans with 5+ implementation tasks
+- Complex features spanning multiple files/modules
+- When context quality matters more than speed
+
+## How It Works
+
+Instead of executing all tasks in one conversation (where context degrades), dispatch a fresh agent per task.
+
+### Per-Task Flow
+
+1. **Dispatch implementer agent** with:
+   - The specific task spec (not the full plan)
+   - Relevant file paths from the plan
+   - Project CLAUDE.md for conventions
+   - Clear success criteria
+
+2. **Agent implements, tests, and reports** with status:
+   - `DONE` — Task complete, tests pass
+   - `DONE_WITH_CONCERNS` — Complete but flagged issues
+   - `NEEDS_CONTEXT` — Missing information, needs clarification
+   - `BLOCKED` — Cannot proceed, needs human input
+
+3. **Review the result**:
+   - Read the agent's output/report
+   - Verify files were created/modified correctly
+   - Run validation on the changes
+
+4. **If DONE**: Mark task complete, move to next
+5. **If issues**: Address them before moving on
+
+### Dispatch Template
+
+When launching a subagent for a task:
+```
+Implement this task from the plan:
+
+**Task**: [task description]
+**Files**: [files to create/modify]
+**Pattern**: [reference pattern from codebase]
+**Tests**: [tests to write]
+**Validation**: [command to verify]
+
+Project conventions are in CLAUDE.md. Follow them strictly.
+Report your status as DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, or BLOCKED.
+```
+
+### Model Selection
+- Use the least powerful model that can handle the task
+- Simple file creation: `haiku`
+- Standard implementation: `sonnet`
+- Complex logic/architecture: `opus`
+
+### Commit Strategy
+- Don't commit after every task (too noisy)
+- Commit at phase boundaries (every 3-5 tasks)
+- Always validate before committing
+
+## Integration with /hopla-execute
+This skill is an ALTERNATIVE to inline execution. Suggest it when:
+- The plan has 5+ tasks
+- The user expresses concern about quality in long sessions
+- Previous executions showed context degradation issues

package/skills/hopla-tdd/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: hopla-tdd
+description: "Test-driven development workflow using the RED-GREEN-REFACTOR cycle. Use when implementing features that require tests, when the plan specifies test tasks, when the user mentions 'TDD', 'test first', 'write tests', or when working on bug fixes that should have regression tests. Do NOT use for documentation, configuration, or tasks where tests don't apply."
+---
+
+# Test-Driven Development (TDD)
+
+## Principle
+**Write the test first, then the code to make it pass.** This ensures every piece of code has a clear purpose and verifiable behavior.
+
+## The RED-GREEN-REFACTOR Cycle
+
+### 🔴 RED: Write a Failing Test
+1. Write a test that describes the expected behavior
+2. Run the test — it MUST fail
+3. Verify it fails for the **right reason** (not a typo or import error)
+4. If it passes immediately, the test isn't testing anything new
+
+### 🟢 GREEN: Make It Pass
+1. Write the **minimum code** to make the test pass
+2. Don't add extra features, optimizations, or edge cases yet
+3. Run the test — it MUST pass now
+4. Run ALL existing tests — they must STILL pass (no regressions)
+
+### 🔵 REFACTOR: Clean Up
+1. Improve the code without changing behavior
+2. Remove duplication, improve naming, simplify logic
+3. Run ALL tests again — everything must still be green
+4. Only refactor when tests are green
+
+## When to Apply TDD
+
+**Strongly recommended for:**
+- New functions, methods, or components
+- Bug fixes (write the reproduction test first)
+- API endpoints and their handlers
+- Data transformations and business logic
+- Utility functions
+
+**Optional for:**
+- Configuration files
+- Simple UI layout changes
+- Documentation
+- Boilerplate with no logic
+- Legacy code without existing test infrastructure
+
+## Integration with /hopla-execute
+
+When executing a plan with TDD:
+1. For each implementation task that has associated tests:
+   - Write the test FIRST (RED)
+   - Then implement the code (GREEN)
+   - Then clean up (REFACTOR)
+2. Validate after each cycle: run the test suite
+3. Don't skip the RED step — it catches specification errors early
+
+## Common Rationalizations (and why they're wrong)
+
+| Rationalization | Why It's Wrong |
+|----------------|---------------|
+| "I'll write tests after" | You'll write tests that match the code, not the spec |
+| "This is too simple to test" | Simple code grows complex. The test documents intent |
+| "It'll be faster without TDD" | Debugging later costs more than testing now |
+| "The test framework isn't set up" | Set it up. It's a one-time cost |
+| "I know this works" | Then the test will pass quickly. Write it anyway |
+
+## Test Quality Guidelines
+
+- **One assertion per test** (when practical)
+- **Clear test names**: `test_user_login_with_invalid_password_returns_401`
+- **Test behavior, not implementation**: Don't test private methods directly
+- **Use real objects** when possible; mock only external dependencies
+- **Tests should be independent**: No shared state between tests