Weekly Rules Review: 2026-03-23

[dyad-assistant]

Weekly Rules Review: 2026-03-23

Summary

Reviewed all 11 rule files in rules/ plus AGENTS.md. Overall the documentation is in good shape — most rules are accurate and reference real patterns. A few items need updates.

---

Rules Audit

rules/electron-ipc.md

Status: ✅ Keep

Reasoning: Core architecture doc. All referenced paths exist (src/ipc/contracts/core.ts, src/ipc/types/index.ts, src/preload.ts, src/ipc/preload/channels.ts, src/ipc/ipc_host.ts, src/ipc/handlers/base.ts, src/lib/queryKeys.ts). Patterns like defineContract, createClient, createStreamClient, writeSettings shallow merge, and ChatResponseChunkSchema incremental streaming are all verified in the codebase.

---

rules/local-agent-tools.md

Status: ✅ Keep

Reasoning: All references verified — modifiesState flag is used across 17+ tool files, buildAgentToolSet exists in tool_definitions.ts, handleLocalAgentStream exists. The stream retry guidance was recently validated by commit 60e7444 (retry transient local agent server errors).

---

rules/e2e-testing.md

Status: ✅ Keep

Reasoning: Comprehensive and actively maintained. References PageObject sub-components, Base UI radio workarounds, Lexical editor tips, snapshot testing, parallel port isolation, and flaky test patterns. All are recurring issues for agents writing E2E tests.

Issues Found:

• Should verify that po.securityReview sub-component still exists (security review feature may have evolved)

---

rules/git-workflow.md

Status: ⚠️ Needs Update

Reasoning: The core workflow is correct, but this file has grown to 149 lines with many very specific rebase conflict resolution tips that are situational and unlikely to recur. These add significant token cost for low probability of reuse.

Suggested Changes:

• Trim the "Conflict resolution tips" section — keep the first 3-4 general tips (modify/delete conflicts, package-lock.json, import conflicts) but remove the highly specific ones about i18n constants, React component wrapper conflicts, and refactoring conflicts. These are one-off scenarios documented as learnings but unlikely to repeat.
• Estimated savings: ~40 lines / ~2KB of tokens

---

rules/base-ui-components.md

Status: ✅ Keep

Reasoning: All referenced components verified — src/components/ui/context-menu.tsx, tooltip.tsx, accordion.tsx all exist and use Base UI. The TooltipTrigger render prop pattern and Accordion API differences from Radix are high-value gotchas.

---

rules/database-drizzle.md

Status: ✅ Keep

Reasoning: Short and focused. drizzle/meta/_journal.json exists. Migration conflict resolution steps are valuable for rebase scenarios.

---

rules/typescript-strict-mode.md

Status: ✅ Keep

Reasoning: All references verified — tsconfig.app.json targets ES2020 with lib: ["ES2020", "DOM", "DOM.Iterable"]. The tsgo installation note and response.json() returns unknown guidance are both high-value.

---

rules/openai-reasoning-models.md

Status: ⚠️ Needs Update

Reasoning: The concept is correct — orphaned reasoning part filtering exists in src/ipc/utils/ai_messages_utils.ts. However, the rule references a function called filterOrphanedReasoningParts() which does not exist as a standalone exported function. The logic is embedded within the cleanMessage() function. Also, src/pro/main/ipc/handlers/local_agent/prepare_step_utils.ts has related reasoning-filtering logic that is not mentioned.

Suggested Changes:

• Update function reference from filterOrphanedReasoningParts() to cleanMessage() in src/ipc/utils/ai_messages_utils.ts
• Mention that prepare_step_utils.ts also handles reasoning part filtering for the local agent

---

rules/adding-settings.md

Status: ✅ Keep

Reasoning: All references verified — UserSettingsSchema in src/lib/schemas.ts, DEFAULT_SETTINGS in src/main/settings.ts, SETTING_IDS in src/lib/settingsSearchIndex.ts, AutoApproveSwitch.tsx exists. Concise and actionable checklist.

---

rules/chat-message-indicators.md

Status: ✅ Keep

Reasoning: dyad-status tag handling verified in src/components/chat/DyadMarkdownParser.tsx. Short (10 lines) and low token cost.

---

rules/product-principles.md

Status: ✅ Keep

Reasoning: Design principles guide for feature planning. Referenced by swarm-to-plan skill. Not code-specific so does not need codebase verification. Provides valuable framing for feature design decisions.

---

AGENTS.md

Status: ✅ Keep

Reasoning: Well-structured index with clear "read when..." guidance. References CONTRIBUTING.md (verified exists). All rule file links are valid.

---

Rules Recommended for Removal

None. All rules provide value. The git-workflow file could be trimmed but not removed.

Rules That Need Updates

File	Change	Priority
rules/openai-reasoning-models.md	Update filterOrphanedReasoningParts() to cleanMessage(), add prepare_step_utils.ts reference	Medium
rules/git-workflow.md	Trim highly specific conflict resolution tips (lines ~117-124) to reduce token cost	Low

Proposed New Rules

1. Media and Image Handling

File: rules/media-handling.md

Problem it solves: Recent commits added media library (#2950), image generation tool (#2789), image selection in visual editor (#2717), image preview (#2918), and image utilities (#2892). Agents working on image/media features lack guidance on where media files are stored, cleanup routines, and how the media library integrates with the agent tools.

Evidence: 5+ commits in the last 30 days touch media/image handling. Commit 620f814 added a cleanup routine for media files, suggesting non-obvious lifecycle management.

Draft content: Media file storage paths, cleanup routine expectations, image generation tool integration, preview iframe image handling.

2. Telemetry and Error Capture

File: rules/telemetry.md

Problem it solves: Recent commits added PostHog exception capture (#2886, #3022), filtered retry 429 telemetry noise (#3024), and improved stream retry telemetry (#2877). Agents modifying error handling or retry logic need to know the telemetry patterns to avoid noise.

Evidence: 4 commits in 30 days specifically dealing with telemetry concerns.

Draft content: PostHog exception capture patterns, what errors to filter vs. report, telemetry noise guidelines for retry/transient errors.

Overall Health Assessment

Score: 8/10 — The documentation is well-maintained and mostly accurate. The rules index in AGENTS.md is clean and well-organized. Most rules reference real, verifiable patterns in the codebase.

Key strengths:

• Concise, actionable rules with code examples
• Good coverage of the most common agent tasks (IPC, E2E, git, UI components)
• Low token overhead for high value (most files are under 2KB)

Areas for improvement:

• git-workflow.md has accumulated situation-specific conflict tips that add token cost without proportional value
• One stale function reference in openai-reasoning-models.md
• New feature areas (media, telemetry) could benefit from lightweight rules as they mature

[dyad-assistant]

Additional Finding: e2e-testing.md inaccuracy

Verification found that rules/e2e-testing.md references po.clearChatInput() and po.openChatHistoryMenu() as direct PageObject methods (lines 64, 74), but these are actually on po.chatActions:

// Current docs say:
await po.clearChatInput();
await po.openChatHistoryMenu();

// Should say:
await po.chatActions.clearChatInput();
await po.chatActions.openChatHistoryMenu();

This contradicts the sub-component pattern documented earlier in the same file. Updated priority table:

File	Change	Priority
rules/e2e-testing.md	Fix po.clearChatInput() to po.chatActions.clearChatInput() and po.openChatHistoryMenu() to po.chatActions.openChatHistoryMenu()	High
rules/openai-reasoning-models.md	Update filterOrphanedReasoningParts() to cleanMessage(), add prepare_step_utils.ts reference	Medium
rules/git-workflow.md	Trim highly specific conflict resolution tips (lines ~117-124) to reduce token cost	Low

[dyad-assistant]

This issue might be a duplicate of existing issues. Please check:

• Weekly Rules Review: 2026-03-16 #3017: Previous weekly rules review from 2026-03-16, covering the same rule files with similar findings (e.g., both flag openai-reasoning-models.md and git-workflow.md for updates) (confidence: medium)

Feel free to ignore if none of these address your specific case.

[dyad-assistant]

Gap Analysis: Patterns From Recent Commits

After scanning commits from the last 30 days, here are additional proposed rules prioritized by evidence of recurring issues:

Proposed New Rule: LiteLLM / AI Message Sanitization

File: rules/ai-message-sanitization.md

Problem it solves: Multiple recent bug fixes relate to message sanitization before sending to LLM providers. Agents modifying this path need to understand the full sanitization pipeline.

Evidence:

• Commit d877467: fix tool-call inputs to prevent LiteLLM invalid dict error
• Commit 60e7444: retry transient local agent server errors
• Commit 9336b07: filter retry 429 telemetry noise

Key patterns:

• cleanMessage() in ai_messages_utils.ts handles orphaned reasoning parts, tool-call input defaults, and itemId stripping
• shouldRetryTransientStreamError() and isRetryableProviderStreamError() classify errors for retry
• LiteLLM bug: empty function.arguments causes invalid dict errors — must default to {}

Proposed New Rule: Engine API Tool Integration

File: rules/engine-api-tools.md

Problem it solves: Three new agent tools (web_fetch, web_crawl, generate_image) all integrate with the Engine API. They share patterns around URL validation, content truncation, and file saving to .dyad/media.

Evidence: Commits dd1e488 (web fetching), ce03bea (image generation), 2397484 (image utilities)

Priority: Low — these are stable and less likely to be modified by agents than IPC or E2E patterns. Worth adding if the tools grow.

Not Recommended for Rules (derivable from code)

The following new features were identified but do NOT need rules files since agents can derive patterns from reading the code:

• Voice input (useVoiceToText.ts) — standard MediaRecorder pattern
• Media library — follows existing IPC contract patterns documented in electron-ipc.md
• Dynamic language model catalog — self-contained module with clear fallback logic
• Planning questionnaire tool — follows existing tool definition patterns in local-agent-tools.md
• Concurrent app running — process manager is self-contained with clear constants