CRITICAL RULES

---
alwaysApply: true
description: Optimized rules prefix with 4-tier hierarchy
---

# CRITICAL RULES

## TIER 0: INSTANT RECOGNITION

**Context**: hass-addons (parent) + python-rebuild-tcp-comm (child)
**Inheritance**: See `inheritance-model.mdc` for parent-child precedence rules
**Phase**: [editing/verifying/documenting - detect from activity]

**Top Anti-Patterns - Quick Check**:

- ❌ **TOUCHING ANY IGNORE FILES OR SETTINGS?** → **ABSOLUTELY FORBIDDEN** (Rule 14: NEVER modify ignore files OR settings)
- ❌ Using built-in web_search? → Wrong (Rule 11: use Brave Search MCP)
- ❌ Tool returns error/500/timeout? → STOP (Rule 1: report to user, don't continue)
- ❌ Creating/editing code without entry/exit logs? → Wrong (Rule 4: Logging-First)
- ❌ Creating 2nd findings file? → STOP (Rule 8: max 1 per investigation)
- ❌ Restarting Python instead of rebuilding? → Wrong (Python = rebuild required)
- ❌ Saying "production-ready" when CI fails? → Wrong (Rule 10: CI must pass)
- ❌ Marking "complete" without user approval? → Wrong (Rule 10: user confirms)
- ❌ Creating files with "FINAL," "COMPLETE," "SUMMARY," etc.? → Ask user first (Rule 10)
- ❌ Using /tmp for artifacts? → Wrong (Use working-files/ with timestamps)
- ❌ Response >30 lines or verbose? → Too long (Rule 8: concise communication)
- ❌ Creating todos for <3 step task? → Overkill (Rule 2: multi-step only)
- ❌ Brave Search for "explain X"? → Wrong (Rule 12: use AI Grounding for answers)
- ❌ AI Grounding to find docs? → Wrong (Rule 12: use Brave Search for pages)
- ❌ Using built-in tools to check for lint errors? → Wrong (Rule 3: use `npm run lint`)

---

## TIER 1: ALWAYS APPLY - EXECUTIVE RULES

**14 CRITICAL RULES (Must Follow)**:

1. **NEVER TOUCH IGNORE FILES**: **ABSOLUTELY FORBIDDEN** to modify, create, or edit ANY ignore file (`.gitignore`, `.markdownlintignore`, `.markdownlint-cli2.jsonc`, `.prettierignore`, `.eslintignore`, `.dockerignore`, or ANY file with "ignore" in the name). If linting errors exist in ignored directories/files, FIX THE ERRORS. **DO NOT JUST SUPPRESS THE ERRORS**. Ask user before even considering touching ignore files.

2. **Development Loop**: Plan → Edit → Rebuild → Verify with Unit Tests and `npm run lint`. STOP if: env error, broken tooling, tool returns error/500/timeout, stale docs, misunderstood requirement. **DON'T WORK AROUND ISSUES** - raise to user immediately.
   - **Key Strategy**: _**AGGRESIVELY**_ ground your Plans and Proposals with the Brave Web Search and Brave AI Grounding tools. See [Brave AI Grounding](/.cursor/rules/brave-ai-grounding-cli.mdc) and [](/.cursor/rules/web-search-brave.mdc) for full details.

3. **Todo Discipline**: WHEN task has 3+ steps → create todos, keep 1 in_progress, update after each step.

4. **Lint-Format-First**: BEFORE finishing a task → run linting and formatting. Treat warnings as errors. No code that fails linting or formatting. `npm run lint` must PASS.

5. **Logging-First**: BEFORE editing code → add entry/exit logs for new functions; NEVER log secrets; set logger AND handler levels from config.

6. **Clean Architecture**: Follow DRY & SOLID principles. Refactor duplication, maintain separation of concerns.

7. **Test Strategy**: Prefer unit over E2E; WHEN running E2E → run sequentially, persist artifacts (text/HTML/JUnit).

8. **Creativity**: Use Python MCP tools to increase efficiency (run code, analyze files, automate tasks).

9. **Concise Communication**: Max 200 lines for AI-created docs (findings, summaries) and `alwaysApply: true` rules. Max 1 findings file per investigation. NO redundant summaries/READMEs. Short sentences, bullets, essential info only. NEVER use /tmp for artifacts - use working-files/ with proper timestamps (see working-files-convention.mdc).

10. **Explain, Don't Assume Error**: WHEN user asks "why" or "how" about implementation → explain reasoning/calculation, THEN ask for confirmation. DON'T immediately assume criticism or error. Example: "why does that header include X files?" → "I calculated it based on A, B, and C. Does that look correct?" NOT "You're right! Let me remove that."

11. **Completion Approval**: NEVER mark as "FINAL," "COMPLETE," "production-ready," "CI-ready," or similar without explicit user approval. NEVER create files with "FINAL," "COMPLETE," "SUMMARY," "RESOLUTION," "CONCLUSION" in the name without asking first. If CI is failing (exit code != 0), the system isn't ready. User confirms = done.

12. **Web Search Only via Brave MCP**: NEVER use built-in `web_search` tool (broken). ALWAYS use `mcp_brave-search_brave_web_search` or specialized tools (`brave_news_search`, `brave_video_search`, `brave_image_search`). Autosearch when uncertain (per memory [[memory:9966253]]). See web-search-brave.mdc.

13. **AI Grounding for Reliable Answers**: WHEN need synthesized, factual answers (not raw search results) → use Brave AI Grounding CLI tool via `run_terminal_cmd`. Responses are anchored in verifiable web sources, reducing hallucinations. Use `--research` flag for complex queries requiring multiple searches. Citations included by default with formatted footer. Prefer over raw search when need: authoritative answers, fact-checking, research with citations, or context about topics. Use regular Brave Search for: finding specific pages, current events, or raw result lists.

14. **Visual Diagrams**: WHEN explaining architecture, flows, processes, or relationships → create Mermaid.js diagrams. Save as `.mermaid` files in appropriate docs directory. Use flowchart (processes), sequence (interactions), class (structure), state (FSM), gantt (timelines), or ER diagrams (data models). See mermaid-diagrams.mdc for templates.

15. **NEVER TOUCH IGNORE FILES**: **ABSOLUTELY FORBIDDEN** to modify, create, or edit ANY ignore file (`.gitignore`, `.markdownlintignore`, `.markdownlint-cli2.jsonc`, `.prettierignore`, `.eslintignore`, `.dockerignore`, or ANY file with "ignore" in the name). If linting errors exist in ignored directories/files, FIX THE ERRORS, NOT THE IGNORE FILES. Ask user before even considering touching ignore files.

---

## Decision Tree - STOP or PROCEED?

**STOP and ask user if**:

- **ANY request to modify/create/edit ignore files** (Rule 0: ABSOLUTELY FORBIDDEN)
- Environment/tooling error or unexpected behavior
- Tool returns error, 500, timeout, or fails to execute
- Documentation appears stale or contradicts reality
- Requirements ambiguous or missing critical info
- Task would take >4 hours or major architectural change
- Multiple valid approaches with different tradeoffs
- Destructive action (force push, delete prod data, etc.)

**PROCEED without asking if**:

- Requirements clear and complete
- Tools working, obvious approach exists
- Standard pattern from rules/docs applies
- <2 hour straightforward implementation
- Non-destructive, easily reversible change

---

**Before-You-Finish Checklists**:

**Code Changes**: [ ] Linted [ ] Tested [ ] Logging [ ] Rebuilt/Restarted [ ] Verified in logs
**Documentation**: [ ] <200 lines [ ] User approved [ ] No redundancy [ ] Single findings file [ ] No /tmp artifacts
**Completion**: [ ] CI passes [ ] User confirmed [ ] Artifacts cleaned [ ] Todos closed [ ] No premature "ready" claims [ ] No "FINAL/COMPLETE" file names without approval

---

## TIER 2: PROJECT-SPECIFIC CRITICAL RULES

**HASS-ADDONS Project** (when in /workspaces/hass-addons):

**Development Workflow**:

- Python changes (.py) → **REBUILD**: `cd cync-controller && ./rebuild.sh`
- Config/static (yaml, html, js, css) → **RESTART**: `ha addons restart local_cync-controller`
- When unsure → **REBUILD** (safer choice)
- Verify → `ha addons logs local_cync-controller --follow`
- NEVER start Docker manually (Supervisor manages it)

**Key Commands**:

- Rebuild: `cd cync-controller && ./rebuild.sh` (includes lint, format, unit tests)
- Restart: `ha addons restart local_cync-controller`
- Logs: `ha addons logs local_cync-controller --follow`
- MQTT cleanup: `sudo python3 scripts/delete-mqtt-safe.py [--dry-run]`

**Critical Patterns**:

- Command callbacks: See critical-commands.mdc for async patterns
- State management: See critical-state-management.mdc for update patterns
- MQTT discovery: Use suggested_area, clean up on changes
- Credentials: Never hardcode, use options/secrets

---

## TIER 3: AVAILABLE REFERENCES (On Demand)

### Available via agent_requestable_workspace_rules - reference as needed

**Critical Guardrails**:

- critical-commands.mdc: Command callback patterns, async handling
- critical-credentials.mdc: Security rules, credential management
- critical-docker.mdc: Docker/devcontainer rules, build patterns
- critical-state-management.mdc: State update patterns, consistency rules

**Logging System**:

- logging-mandatory.mdc: When and how to log (MUST READ before adding logs)
- logging-patterns.mdc: Configuration patterns, anti-patterns
- logging-examples.mdc: Code examples and templates

**Documentation & Standards**:

- inheritance-model.mdc: Parent-child rule precedence and context detection
- documentation-standards.mdc: Concise docs, anti-verbosity rules, approval workflow
- working-files-convention.mdc: Timestamp format, directory structure, cleanup
- documentation-archiving.mdc: Where and how to document completed work
- mermaid-diagrams.mdc: Visual diagram patterns, templates, best practices

**Development Patterns**:

- development-workflow.mdc: Full 3-step process details
- python-changes-require-rebuild.mdc: Why Python requires rebuild
- testing-workflows.mdc: Testing procedures and patterns
- architecture-concepts.mdc: Key architectural patterns

**Helper Tools**:

- helper-scripts.mdc: Automation scripts available
- mqtt-entity-cleanup.mdc: Entity deletion workflows
- ai-browser-testing.mdc: Playwright patterns for testing
- mcp-tools-guide.mdc: MCP development tools usage
- web-search-brave.mdc: Brave Search MCP usage (REQUIRED for all web searches)
- brave-ai-grounding-cli.mdc: AI Grounding CLI tool usage, streaming responses, citations

**Environment & Setup**:

- devcontainer-quirks.mdc: Dev environment setup and quirks
- dns-requirements.mdc: DNS redirection setup (REQUIRED)
- token-creation-flow.mdc: Automated LLAT creation
- supervisor-api-access.mdc: API patterns and auth

**Reference Only**:

- daily-dev-cheatsheet.mdc: Common commands quick reference
- git-practices.mdc: Git workflow and commit guidelines (prepare changes, user commits)
- performance-tuning.mdc: Optimization patterns
- known-bugs-workarounds.mdc: Bug patterns and workarounds
- cloud-relay-patterns.mdc: Relay mode usage and limitations
- shell-scripting.mdc: Shell script standards
- mqtt-integration.mdc: MQTT discovery patterns
- debugging-with-logs.mdc: Debugging and log inspection techniques