From 7da4373cc1bac902b3bf825272a05b24e11ef54f Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 2 Feb 2026 13:49:03 -0500 Subject: [PATCH] docs: Update verification scripts README with enhanced output documentation - Document detailed error/warning output patterns - Show examples of enhanced information provided - Explain specific content found for each violation type - Include examples for both errors and warnings - Demonstrate improved user experience with actionable details This documents the latest enhancement where verification scripts now provide specific file paths, line numbers, and content details instead of generic error messages, making issues easier to understand and resolve for both humans and AI assistance. --- scripts/README.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/scripts/README.md b/scripts/README.md index eedb5ba..89061ec 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -96,14 +96,19 @@ Use `make verify-guidelines` for comprehensive validation: ### When Issues Are Found: +#### Enhanced Error/Warning Output (Latest): +Both scripts now provide detailed information for all issues found: + #### For Errors (Critical Violations): ```bash # Example: AI detects local binary ❌ ERROR: Found 1 binary files (should build through Dockerfile) AI INSTRUCTION: Ask user before fixing this issue +Found files: +./server # AI should respond: -"I found a binary file 'server' which violates the guideline 'NEVER build server binaries locally - all builds through Dockerfile/docker-compose'. This file should be removed since builds should go through containers. +"I found a binary file './server' which violates the guideline 'NEVER build server binaries locally - all builds through Dockerfile/docker-compose'. This file should be removed since builds should go through containers. Do you want me to fix this? [y/n]" ``` @@ -111,15 +116,34 @@ Do you want me to fix this? [y/n]" #### For Warnings (Documentation/Style Issues): ```bash # Example: AI finds API content in README -⚠ WARNING: Found API patterns in README.md (may be legitimate for breaking changes) +⚠ WARNING: Found 2 API patterns in README.md (verify placement per guidelines) AI INSTRUCTION: Ask user before fixing this issue +Found patterns: +81:- **Rate Limiting**: 10 requests/minute on auth endpoints +98:- **[docs/api/WEBSOCKET_API.md](docs/api/WEBSOCKET_API.md)** - WebSocket protocol # AI should respond: "I found API documentation patterns in README.md. According to the guidelines, API endpoints should be in 'docs/api//.md' unless this is a breaking change. +The specific patterns found are: +- Line 81: Rate limiting information +- Line 98: WebSocket API reference + Do you want me to fix this? [y/n]" ``` +#### Detailed Information Provided: +- **Binary files**: Lists exact file paths found +- **CSS violations**: Shows specific templates with