Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: Update verification scripts README with enhanced output documentation

Browse Source 
- 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.
This commit is contained in:
john-okeefe
2026-02-02 13:49:03 -05:00
parent c78e520f22
commit 7da4373cc1
1 changed files with 26 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/README.md
+26 -2
View File
@@ -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/<category>/<endpoint>.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 <style> tags
- **JavaScript files**: Lists all .js files outside allowed directories
- **Build failures**: Displays compilation error logs
- **Missing files**: Shows expected file locations and purposes
- **Git ignore issues**: Displays current .gitignore contents
- **API content**: Shows exact lines and patterns found
- **Dockerfile proliferation**: Lists all Dockerfile variants found
- **Large commits**: Shows specific commits with file counts
- **Bruno coverage**: Compares API docs vs test file counts
## Recent Enhancements
### AI Behavior Protocol Implementation (Latest):