feat(docs): add frontend debugging guide with browser verification patterns#69
Conversation
…tterns - Add tools/ui/frontend-debugging.md covering hydration errors, monorepo gotchas - Update bug-fixing workflow with frontend verification warning - Add progressive disclosure trigger for frontend debugging - Store memory entries for SVGR, curl verification, hydration patterns Learned from AwardsApp session where curl returned 200 but site showed React hydration error. Browser screenshot revealed the actual issue.
WalkthroughThis PR introduces a comprehensive Frontend Debugging Guide to the agent tooling ecosystem, registers it in the agent manifest under UI tooling, and extends bug-fixing workflows with critical browser-based verification guidance to replace unreliable HTTP status code checks. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello @marcusquinn, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a crucial documentation resource aimed at improving the debugging process for frontend applications, particularly those built with React/Next.js within a monorepo structure. It provides clear guidance on common pitfalls such as the unreliability of Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Tue Jan 13 14:23:23 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds excellent and much-needed documentation on frontend debugging, covering crucial topics like browser verification over curl, React hydration errors, and common monorepo pitfalls with webpack loaders. The new guide is comprehensive, well-structured, and provides actionable code examples and scripts. The updates to AGENTS.md and bug-fixing.md effectively integrate this new knowledge into existing workflows. My review includes a couple of minor suggestions for the new guide to improve the robustness of a script and the internal consistency of an example.
| const hasError = await page.evaluate(() => { | ||
| const body = document.body.innerText; | ||
| return body.includes("Something went wrong") || | ||
| body.includes("Error:") || | ||
| body.includes("Unhandled Runtime Error"); | ||
| }); |
There was a problem hiding this comment.
For more robust error detection, it's a good practice to make the search for error messages case-insensitive. This will prevent missing errors that might be capitalized differently (e.g., "error:" vs "Error:").
| const hasError = await page.evaluate(() => { | |
| const body = document.body.innerText; | |
| return body.includes("Something went wrong") || | |
| body.includes("Error:") || | |
| body.includes("Unhandled Runtime Error"); | |
| }); | |
| const hasError = await page.evaluate(() => { | |
| const body = document.body.innerText.toLowerCase(); | |
| return body.includes("something went wrong") || | |
| body.includes("error:") || | |
| body.includes("unhandled runtime error"); | |
| }); |
| **Option 1: Inline SVG Components (Recommended)** | ||
|
|
||
| ```typescript | ||
| // packages/ui/shared/src/assets/icons.tsx |
There was a problem hiding this comment.
For consistency with the file structure example provided earlier in the document (lines 157-161), the file path in this comment should probably be // packages/ui/src/assets/icons.tsx or simply // packages/ui/src/icons.tsx. The current path introduces a shared directory which wasn't mentioned before, potentially causing confusion.
| // packages/ui/shared/src/assets/icons.tsx | |
| // packages/ui/src/assets/icons.tsx |
🤖 Augment PR SummarySummary: Adds a frontend debugging guide that codifies a key lesson from a React/Next.js incident: a 200 OK HTML response doesn’t guarantee the browser app is working. Changes:
Technical Notes: The guidance centers on validating fixes via 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
.agent/tools/ui/frontend-debugging.md (1)
60-93: Consider adding connection error handling guidance.The browser verification script is well-structured, but could benefit from basic error handling if
dev-browserisn't running or the connection fails.💡 Optional: Add error handling example
Consider adding a note about verifying the dev-browser is accessible before the script:
# Verify dev-browser is running before attempting verification if ! curl -s http://localhost:9222/json/version >/dev/null 2>&1; then echo "ERROR: dev-browser not responding on port 9222" echo "Run: bash ~/.aidevops/agents/scripts/dev-browser-helper.sh start" exit 1 fi # Then proceed with the TypeScript verification...This helps users diagnose connectivity issues more quickly.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
.agent/AGENTS.md.agent/tools/ui/frontend-debugging.md.agent/workflows/bug-fixing.md
🧰 Additional context used
🧠 Learnings (4)
📚 Learning: 2026-01-06T15:57:56.007Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.007Z
Learning: Applies to **/.agent/scripts/linters-local.sh : Run quality checks before committing using .agent/scripts/linters-local.sh
Applied to files:
.agent/workflows/bug-fixing.md
📚 Learning: 2025-12-22T01:24:53.937Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: templates/home/AGENTS.md:0-0
Timestamp: 2025-12-22T01:24:53.937Z
Learning: Follow all security protocols and working directory specifications defined in ~/Git/aidevops/AGENTS.md
Applied to files:
.agent/workflows/bug-fixing.md
📚 Learning: 2025-11-29T04:34:42.033Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Reference AGENTS.md (authoritative) instead of AGENT.md for AI assistant guidance
Applied to files:
.agent/AGENTS.md
📚 Learning: 2026-01-06T15:57:56.008Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.008Z
Learning: Applies to **/AGENTS.md : Use progressive disclosure in AGENTS.md with pointers to subagents rather than inline content
Applied to files:
.agent/AGENTS.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (9)
.agent/tools/ui/frontend-debugging.md (6)
1-13: LGTM! Well-configured frontmatter.The tool permissions are appropriately scoped for a debugging guide—read-only with bash/grep for verification scripts, no write permissions to prevent accidental modifications during debugging.
15-33: Excellent progressive disclosure pattern.The Quick Reference provides clear triggers for when to consult this guide, and the golden rule ("Always verify frontend fixes with browser screenshot, never trust curl alone") is prominently featured for quick scanning.
106-144: Excellent capture of real-world debugging patterns!The hydration errors section documents valuable tribal knowledge, especially the "got: object" pattern derived from actual debugging sessions. The table of error messages with causes and solutions provides quick reference value, and the SVGR import example clearly demonstrates the monorepo package boundary issue.
146-226: Comprehensive and technically accurate monorepo guidance.This section clearly explains the webpack loader boundary issue and provides three viable solutions with appropriate trade-offs. Marking inline SVG components as the recommended approach is sound advice for simplicity and maintainability. The detection checklist provides actionable prevention measures.
228-278: Clear step-by-step debugging workflow.The five-step workflow provides a logical progression from reproduction through verification, with practical scripts for each step. The console error capture in Step 2 properly uses CDP event listeners, and Step 4's typeof debugging is a pragmatic approach to identifying import type issues.
280-284: Appropriate cross-references to related documentation.The related resources provide logical navigation paths to browser automation, React patterns, and build debugging workflows.
.agent/workflows/bug-fixing.md (1)
94-112: Excellent integration of frontend verification guidance.The new section is strategically placed within the Testing workflow, uses consistent examples and explanations from the detailed frontend-debugging.md guide, and appropriately uses progressive disclosure by referencing the full workflow rather than duplicating it.
The (CRITICAL) emphasis is warranted given that curl-based verification is a common pitfall that wastes debugging time.
.agent/AGENTS.md (2)
384-384: Proper integration into Subagent Folders table.The tools/ui/ row is correctly updated to include frontend-debugging in both the description (mentioning hydration errors as a key topic) and the key subagents list, maintaining consistency with the table format.
460-460: Progressive disclosure entry properly added.The new row follows the table format, correctly references the frontend-debugging.md path, and highlights the key topics (hydration errors, monorepo gotchas) that would trigger an AI to consult this guide. Placement near browser automation is logical for frontend-related task grouping.
1 participant
Summary
Adds documentation and progressive disclosure patterns learned from an AwardsApp debugging session where:
curlreturned HTTP 200 with valid HTMLChanges
New:
tools/ui/frontend-debugging.md- Comprehensive guide covering:Updated:
workflows/bug-fixing.md- Added frontend verification warningUpdated:
AGENTS.md- Progressive disclosure trigger for frontend debuggingKey Learnings Documented
Testing
These are documentation-only changes. After merge, run
./setup.shto deploy.Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.