AI Agent Instructions for WP Code Check

Quick Links:

Main README - User-facing documentation
Template Guide - Manual template creation
MCP Documentation - AI integration via Model Context Protocol

Overview

Complete end-to-end workflow:

Phase 1a: Check for existing templates in dist/TEMPLATES/
Phase 1b: Complete template if needed (extract metadata + optional GitHub repo)
Phase 1c: Run scan using template or direct path
Phase 2: AI-assisted triage of findings
Phase 3: Create GitHub issue (automated or manual)

Workflow Decision Tree:

User Request
    │
    ├─ "Run [name] end to end" ──────► Execute all phases (1c → 2 → 3)
    │
    ├─ "Run [name] scan" ─────────────► Phase 1c only (scan)
    │
    ├─ "Complete template [name]" ────► Phase 1b (metadata extraction)
    │
    ├─ "Triage [scan-id]" ────────────► Phase 2 only (AI analysis)
    │
    └─ "Create issue [scan-id]" ──────► Phase 3 only (GitHub issue)

End-to-End Execution Mode

When a user requests "Run template [name] end to end", execute the complete automated pipeline:

Run scan → Generate JSON log (Phase 1c)
AI triage → Analyze findings and update JSON (Phase 2)
Generate HTML → Create final report with AI summary (Phase 2) ⚠️ MUST happen AFTER triage
Create GitHub issue → Automated or manual (Phase 3)

No manual intervention required - the AI agent handles all phases automatically.

Example user requests:

"Run template gravityforms end to end"
"Execute woocommerce end to end"
"Run gravityforms complete workflow"
"Scan, triage, and create GitHub issue for hypercart-helper"

⚠️ CRITICAL: Orchestration Sequence

The HTML report MUST be regenerated AFTER AI triage is complete. This is the most important rule to prevent missing AI triage data in the final report.

Correct Sequence:

1. Run scan → JSON created
2. AI triage → JSON updated with ai_triage section
3. Regenerate HTML → HTML includes AI triage data
4. Create GitHub issue → Issue includes AI classifications

Incorrect Sequence (DO NOT DO THIS):

❌ 1. Run scan → JSON created
❌ 2. Generate HTML → HTML created WITHOUT ai_triage data
❌ 3. AI triage → JSON updated, but HTML is stale
❌ 4. Create GitHub issue → Issue missing AI classifications

AI Agent Actions (Correct Order):

Execute scan: dist/bin/run [template-name] (wait for completion)
Locate generated JSON: dist/logs/[TIMESTAMP].json
- For scans generated with WP Code Check 1.3.36 or later, this file is a single valid JSON document.
- For scans generated by earlier versions, the log may contain non-JSON lines (for example Python tracebacks) before the JSON payload. When analyzing an older log, strip everything before the first line that starts with { or prefer rerunning the scan on a newer version.
Perform AI triage analysis (read JSON, analyze findings)
Update JSON with ai_triage section
Regenerate HTML: python3 dist/bin/json-to-html.py [json] [html] ← Must happen AFTER step 4
Create GitHub issue: dist/bin/create-github-issue.sh --scan-id [TIMESTAMP]
Report completion with final HTML report and GitHub issue URL (if created)

Error Handling:

If scan fails → stop and report error
If triage fails → generate basic HTML without AI summary, report issue to user
If GitHub issue creation fails → issue body saved to dist/issues/ for manual use
Provide progress updates as each phase completes

Verification Checklist:

JSON log created and contains findings
AI triage analysis completed
JSON updated with ai_triage section (verify with jq '.ai_triage' dist/logs/[TIMESTAMP].json)
HTML regenerated AFTER triage (verify with grep -c 'ai_triage\|AI Triage\|False Positives' dist/reports/[TIMESTAMP].html)
HTML report opened in browser to confirm AI summary is visible

Phase 1a: Check for Existing Templates

ALWAYS start here. Look for an existing template matching the plugin/theme name.

ls -1 /Users/noelsaw/Documents/GitHub\ Repos/wp-code-check/dist/TEMPLATES/*.txt

Template Naming Best Practices

Preferred naming convention: Lowercase with hyphens

✅ Recommended	⚠️ Acceptable	❌ Avoid
`gravity-forms.txt`	`gravityforms.txt`	`Gravity Forms.txt`
`woocommerce.txt`	`woo_commerce.txt`	`WooCommerce.txt`
`twenty-twenty-four.txt`	`twentytwentyfour.txt`	`Twenty Twenty Four.txt`

Why lowercase with hyphens?

Consistent with WordPress plugin slug conventions
Easier to type and autocomplete
Avoids shell escaping issues with spaces
Matches GitHub repository naming patterns

Template Detection Logic

When user says "Run [name]", try these variations in order:

Exact match: [name].txt
Lowercase: [name-lowercase].txt
With hyphens: Replace spaces/underscores with hyphens
Without hyphens: Remove all separators

Example: User says "Run Gravity Forms"

# Try in this order:
1. Gravity Forms.txt
2. gravity forms.txt
3. gravity-forms.txt
4. gravityforms.txt

If a template exists, skip to Phase 1c: Running Scans.

Phase 1b: Template Completion (If Needed)

When to Complete a Template

User creates a new .txt file in dist/TEMPLATES/ with just a path, or asks you to complete one.

Example only: User creates dist/TEMPLATES/gravityforms.txt with:

/Users/noelsaw/Local Sites/my-site/app/public/wp-content/plugins/gravityforms

Steps to Complete a Template

Step 1: Read the user's file to extract the path

Step 2: Extract plugin/theme metadata

Navigate to the path
Find the main PHP file (usually matches folder name, e.g., gravityforms.php)

Parse the plugin header:

/**
 * Plugin Name: Gravity Forms
 * Version: 2.7.1
 * Description: ...
 */

Extract Plugin Name and Version

Step 2b: Detect GitHub repository (OPTIONAL)

Check if the plugin/theme has a GitHub repository using these methods:

Method 1: Plugin/Theme Headers

# Search for GitHub URLs in main plugin file
grep -E "(Plugin URI|Theme URI|GitHub Plugin URI):" [main-file.php]

Common header fields:

Plugin URI: - Official plugin homepage (may be GitHub)
GitHub Plugin URI: - GitHub Updater plugin convention
Theme URI: - Official theme homepage

Method 2: README Files

# Search readme.txt for GitHub links
grep -i "github.com" readme.txt

# Search README.md for repository links
grep -E "\[.*\]\(https://github.com/[^)]+\)" README.md

Method 3: Git Remote (if .git folder exists)

cd [plugin-path]
git config --get remote.origin.url
# Example output: https://github.com/owner/repo.git

Extraction Patterns:

Source	Pattern	Example
URL	`github.com/([^/]+)/([^/]+)`	`github.com/woocommerce/woocommerce` → `woocommerce/woocommerce`
Git remote	`github.com[:/]([^/]+)/(.+?)(.git)?$`	`git@github.com:owner/repo.git` → `owner/repo`

Important Rules:

✅ Only use if you find explicit GitHub references
✅ Verify the URL points to the actual plugin/theme repository (not a fork or unrelated project)
❌ DO NOT guess or make up repository URLs
❌ DO NOT use WordPress.org plugin pages as GitHub repos
⚠️ If uncertain, leave GITHUB_REPO commented out

Example valid detections:

# Plugin header
Plugin URI: https://github.com/gravityforms/gravityforms
→ GITHUB_REPO='gravityforms/gravityforms'

# Git remote
git@github.com:woocommerce/woocommerce.git
→ GITHUB_REPO='woocommerce/woocommerce'

# README.md
[View on GitHub](https://github.com/Automattic/jetpack)
→ GITHUB_REPO='Automattic/jetpack'

Example invalid detections:

# WordPress.org plugin page (NOT GitHub)
Plugin URI: https://wordpress.org/plugins/woocommerce/
→ Leave GITHUB_REPO commented out

# Generic company website
Plugin URI: https://gravityforms.com
→ Leave GITHUB_REPO commented out

Step 3: Generate the template using this structure:

# WP Code Check - Project Configuration Template
# Auto-generated on YYYY-MM-DD

# ============================================================
# BASIC CONFIGURATION
# ============================================================

PROJECT_NAME=gravityforms
PROJECT_PATH='/Users/noelsaw/Local Sites/my-site/app/public/wp-content/plugins/gravityforms'
NAME='Gravity Forms'
VERSION='2.7.1'

# GitHub repository (OPTIONAL)
# Used for automated GitHub issue creation
# Format: owner/repo (e.g., gravityforms/gravityforms)
# Or full URL: https://github.com/owner/repo
# GITHUB_REPO=''

# ============================================================
# COMMON OPTIONS
# ============================================================

# SKIP_RULES=
# MAX_ERRORS=0
# MAX_WARNINGS=10

# ============================================================
# OUTPUT OPTIONS
# ============================================================

# FORMAT=json
# SHOW_FULL_PATHS=false

# ============================================================
# ADVANCED OPTIONS
# ============================================================

# BASELINE=.hcc-baseline
# LOG_DIR=./logs
# EXCLUDE_PATTERN=node_modules|vendor
# MAX_FILE_SIZE_KB=1000
# PARALLEL_JOBS=4

Step 4: Handle errors gracefully

If you can't find the plugin file, create the template anyway
Add a warning comment: # WARNING: Could not auto-detect plugin metadata. Please fill in NAME and VERSION manually.
Explain what went wrong to the user

Important Notes

Always preserve the user's original path
Don't uncomment optional settings unless asked
Add timestamps in the header
Validate the path exists before completing
Use lowercase-with-hyphens naming convention for new templates

Cross-Reference: See Template Guide for manual template creation and configuration options.

Phase 1c: Running Scans

How Users Should Ask the AI Agent

Users can ask the AI agent to run a template in natural language:

Examples of valid requests (scan only):

"Run the gravityforms template"
"Scan gravityforms"
"Run gravityforms scan"
"Execute the gravityforms template"
"Perform a scan on gravityforms"

Examples of valid requests (end-to-end with AI triage):

"Run template gravityforms end to end"
"Execute woocommerce end to end"
"Run gravityforms complete workflow"
"Scan and triage gravityforms"

AI Agent: How to Run Templates

Step 1: Determine the template name

User says: "Run the gravityforms template"
Template name: gravityforms
Template file: dist/TEMPLATES/gravityforms.txt

Step 2: Try filename variations If the exact filename doesn't exist, try these variations:

Exact name: gravityforms.txt
With hyphens: gravity-forms.txt
With underscores: gravity_forms.txt
With spaces (escaped): gravity\ forms.txt

Step 3: Run the template

/Users/noelsaw/Documents/GitHub\ Repos/wp-code-check/dist/bin/run gravityforms

Step 4: Wait for completion

Scans typically take 1-2 minutes for large plugins
JSON log will be saved to dist/logs/TIMESTAMP.json
HTML report will be auto-generated to dist/reports/TIMESTAMP.html

Using Direct Paths (If No Template Exists)

/Users/noelsaw/Documents/GitHub\ Repos/wp-code-check/dist/bin/check-performance.sh --paths /path/to/plugin --format json

Output Locations

JSON logs: dist/logs/TIMESTAMP.json
HTML reports: dist/reports/TIMESTAMP.html (auto-generated from JSON)

Note: If HTML generation fails during scan, use the standalone converter:

python3 dist/bin/json-to-html.py dist/logs/[TIMESTAMP].json dist/reports/[TIMESTAMP].html

See Manual JSON to HTML Conversion section below for troubleshooting.

Phase 2: AI-Assisted Triage

After HTML report is generated, perform a 2nd pass AI triage on the generated JSON log to identify false positives and provide an overall assessment.

Scan the actual files that were flagged to determine if the finding is valid.

Purpose: Reduce noise by identifying false positives and providing actionable recommendations.

When to Use

Automatically: When user requests "end to end" execution
Manually: User explicitly asks "Run AI triage on this report"
User wants to validate false positives before publishing
User needs an executive summary of findings
Preparing findings for stakeholder review or GitHub issue creation

The Experimental Golden Analyzer PHP script is not the AI assisted triage. Your analysis of the JSON log against the codebase is the AI assisted triage.

Cross-Reference: See README - AI-Assisted Triage for feature overview.

HTML Report Layout

Phase 2 section appears at the TOP of the HTML report (TL;DR format):

Summary stats grid (Reviewed, Confirmed, False Positives, Needs Review, Confidence)
Overall narrative (3-5 paragraphs) covering:
- Overview of findings and confirmed issues
- False positives explanation with percentage
- Items needing manual review
- Recommendations list
- Next steps guidance

Users see the summary immediately without scrolling.

Workflow Steps

Step 1: Read the JSON log

cat dist/logs/TIMESTAMP.json | jq '.findings[] | {id, severity, file, line}'

Step 2: Analyze findings for false positives

Check for phpcs:ignore comments with justification
Verify nonce/capability checks nearby
Look for adjacent sanitization functions
Identify string literal matches vs actual superglobal access

Step 3: Update the JSON with triage summary and recommendations

import json
from datetime import datetime

# Read existing JSON
with open('dist/logs/TIMESTAMP.json', 'r') as f:
    data = json.load(f)

# Inject ai_triage data (overall summary format)
data['ai_triage'] = {
    'performed': True,
    'status': 'complete',
    'timestamp': datetime.utcnow().isoformat() + 'Z',
    'version': '1.0',
    'summary': {
        'findings_reviewed': 10,
        'confirmed_issues': 2,
        'false_positives': 7,
        'needs_review': 1,
        'confidence_level': 'high'
    },
    'recommendations': [
        'Priority 1: Fix unsafe RegExp in repeater.js (line 126)',
        'Priority 2: Review minified JS source for obfuscation',
        'Consider adding baseline file to suppress known false positives'
    ]
}

# Write updated JSON
with open('dist/logs/TIMESTAMP.json', 'w') as f:
    json.dump(data, f, indent=2)

Step 4: Re-generate HTML

python3 dist/bin/json-to-html.py dist/logs/TIMESTAMP.json dist/reports/TIMESTAMP.html

The HTML report will now show:

Summary stats at top
Overall narrative explaining the findings
Detailed findings section below for reference

Summary Stats

Stat	Meaning
Reviewed	Total findings analyzed
Confirmed	Real issues requiring action (green)
False Positives	Safe to ignore, have safeguards (gray)
Needs Review	Ambiguous, require human judgment (yellow)
Confidence	Overall confidence level of analysis

Confidence Levels

Level	Meaning	When to Use
`high`	90%+ confident in this assessment	Clear patterns, definitive evidence
`medium`	60-89% confident	Some ambiguity, context-dependent
`low`	<60% confident, needs human review	Insufficient context, complex logic

Tip: When confidence is low, add specific questions in the needs_review section to guide manual review.

Phase 3: GitHub Issue Creation

After AI triage is complete, create a GitHub issue with the findings.

Purpose: Convert scan findings into actionable GitHub issues with checkboxes and priority ordering.

When to Use

Automatically: When user requests "end to end" execution with GitHub repo configured
Manually: User explicitly asks "Create GitHub issue for this scan"
User wants to track findings in their project management system
User needs to share findings with their team
Preparing findings for external stakeholders or clients

Cross-Reference: See README - GitHub Issue Creation for feature overview and multi-platform support.

Prerequisites

✅ Scan completed with JSON log
✅ AI triage performed (JSON has ai_triage section)
⚠️ GitHub CLI (gh) installed and authenticated (only for automated creation)
⚠️ GitHub repo specified (via --repo flag or GITHUB_REPO in template) - OPTIONAL

Workflow Steps

Step 1: Determine the scan ID

# Scan ID is the timestamp from the JSON filename
# Example: dist/logs/2026-01-13-031719-UTC.json
# Scan ID: 2026-01-13-031719-UTC

Step 2: Run the GitHub issue creator

Option A: Automated (with GitHub repo)

# If template has GITHUB_REPO field
./dist/bin/create-github-issue.sh --scan-id 2026-01-13-031719-UTC

# Or specify repo manually
./dist/bin/create-github-issue.sh --scan-id 2026-01-13-031719-UTC --repo owner/repo

Option B: Manual (without GitHub repo)

# No repo specified - saves to dist/issues/ for manual copy/paste
./dist/bin/create-github-issue.sh --scan-id 2026-01-13-031719-UTC
# → Saves to: dist/issues/GH-issue-2026-01-13-031719-UTC.md

Step 3: Handle the result

If automated creation succeeds:

GitHub issue URL will be displayed
Issue includes:
- Scan metadata (plugin/theme name, version, date)
- Summary counts (confirmed issues, needs review, false positives)
- Confirmed issues section with checkboxes
- Needs review section with confidence levels
- Local file paths to reports

If no GitHub repo specified:

Issue body saved to dist/issues/GH-issue-{SCAN_ID}.md
User can manually copy/paste to:
- GitHub (create issue manually)
- Jira, Linear, Asana, Trello, Monday.com
- Internal documentation
- Email or Slack

Output Locations

All outputs use matching UTC timestamps for easy correlation:

dist/logs/2026-01-13-031719-UTC.json          # Scan data with AI triage
dist/reports/2026-01-13-031719-UTC.html       # HTML report with AI summary
dist/issues/GH-issue-2026-01-13-031719-UTC.md # Issue body (if no repo)

GitHub Issue Format

The generated issue includes:

# WP Code Check Review - {SCAN_ID}

**Scanned:** {Date in local timezone}
**Plugin/Theme:** {Name} v{Version}
**Scanner Version:** {Version}

**Summary:** {total} findings | {confirmed} confirmed issues | {needs_review} need review | {false_positives} false positives

---

## ✅ Confirmed by AI Triage
- [ ] **{Rationale}...**
  `{file}:{line}` | Rule: `{rule_id}`

---

## 🔍 Most Critical but Unconfirmed

- [ ] **{Classification} ({confidence} confidence)**
  `{file}:{line}` | Rule: `{rule_id}`

---

**Local Reports:**

HTML Report: dist/reports/{SCAN_ID}.html JSON Report: dist/logs/{SCAN_ID}.json


**Powered by:** [WPCodeCheck.com](https://wpCodeCheck.com)

Error Handling

Scenario	Behavior	User Action
No GitHub repo specified	✅ Saves to `dist/issues/`	Copy/paste manually to GitHub or PM app
GitHub CLI not installed	❌ Error message	Install `gh` CLI or use manual workflow
GitHub CLI not authenticated	❌ Error message	Run `gh auth login`
No AI triage data	⚠️ Warning	Run AI triage first (Phase 2)
Invalid scan ID	❌ Error message	Check scan ID matches JSON filename

Best Practices

Always run AI triage first - GitHub issues are more useful with confirmed/false positive classifications
Use templates with GITHUB_REPO - Enables fully automated workflow
Review before creating - Script shows preview and asks for confirmation
Keep issue bodies - Files in dist/issues/ are not tracked by Git, safe to keep for reference
Use issue bodies for other platforms - Copy/paste to Jira, Linear, Asana, Trello, Monday.com, etc.

Multi-Platform Workflow:

# Generate issue body without creating GitHub issue
./dist/bin/create-github-issue.sh --scan-id [TIMESTAMP]

# Copy from dist/issues/GH-issue-[TIMESTAMP].md to:
# - Jira (paste as description)
# - Linear (paste as issue description)
# - Asana (paste as task description)
# - Trello (paste as card description)
# - Email or Slack (formatted markdown)

Common False Positive Patterns

Understanding these patterns helps AI agents provide accurate triage assessments.

Rule ID	Common False Positive Reason	How to Verify
`spo-002-superglobals`	Has `phpcs:ignore` with nonce verification elsewhere in function	Check for `wp_verify_nonce()` or `check_admin_referer()` in same function
`rest-no-pagination`	Endpoint returns single item, not collection (e.g., `/item/{id}`)	Check if route has `{id}` parameter or returns single object
`get-users-no-limit`	Args passed through `apply_filters()` hook that adds limit	Look for `apply_filters()` wrapping the args array
`direct-db-query`	Query uses `$wpdb->prepare()` on adjacent line (multi-line query)	Check 1-3 lines above/below for `$wpdb->prepare()`
`admin-no-cap-check`	Function is only called from another function that has cap check	Trace function calls to see if parent has `current_user_can()`
`n-plus-1-pattern`	Meta call in view/template with bounded field count	Check if loop iterates over small, fixed set of custom fields
`n-plus-1-pattern`	Meta call in email context (low frequency)	Verify email send frequency and whether it runs async
`n-plus-1-pattern`	Caching present nearby (transients/object cache)	Look for `get_transient()`, `set_transient()`, or `wp_cache_get()`
`n-plus-1-pattern`	Loop is bounded by LIMIT or array_slice	Verify maximum iteration count is small (< 20)
`n-plus-1-pattern`	Admin-only context with low traffic	Check if page is high-traffic or dataset could grow large
`unsafe-regexp`	RegExp pattern is static/hardcoded, not user input	Check if pattern comes from variable or is a string literal
`debug-code`	Debug code in vendor/node_modules directory	Check file path - third-party code is not under developer control

AI Agent Tip: When analyzing findings, always read 5-10 lines of context around the flagged line to catch these patterns.

Cross-Reference: See README - Quick Scanner for complete list of checks and severity levels.

Manual JSON to HTML Conversion

If HTML generation fails during a scan, use the standalone Python converter.

When to use:

Main scan completes but HTML report generation hangs or times out
Need to regenerate HTML after updating JSON with AI triage data
Want to create custom HTML reports from existing JSON logs

Basic usage:

# Convert specific JSON to HTML
python3 dist/bin/json-to-html.py dist/logs/[TIMESTAMP].json dist/reports/[TIMESTAMP].html

# Find latest JSON log and convert
latest_json=$(ls -t dist/logs/*.json | head -1)
python3 dist/bin/json-to-html.py "$latest_json" dist/reports/manual-report.html

Features:

✅ Fast & Reliable - Python-based, no bash subprocess issues
✅ Standalone - Works independently of main scanner
✅ Auto-opens - Automatically opens report in browser (macOS/Linux)
✅ No Dependencies - Uses only Python 3 standard library
✅ Detailed Output - Shows progress and file size

Troubleshooting:

Error	Solution
`python3: command not found`	Install Python 3: `brew install python3` (macOS) or `apt install python3` (Linux)
`FileNotFoundError: report-template.html`	Ensure `dist/bin/templates/report-template.html` exists
`JSONDecodeError`	Validate JSON: `jq empty dist/logs/[file].json`
`Permission denied`	Make script executable: `chmod +x dist/bin/json-to-html.py`

Cross-Reference: See README - JSON to HTML Converter for integration with main scanner.

Troubleshooting

Common Errors and Solutions

Error	Likely Cause	Solution
`Permission denied`	Script not executable	`chmod +x /path/to/script.sh`
`No such file or directory`	Incorrect path or file doesn't exist	Use absolute path, verify with `ls -la`
`python3: command not found`	Python 3 not installed	Install: `brew install python3` (macOS) or `apt install python3` (Linux)
`Invalid JSON`	Corrupted or incomplete JSON log	Validate: `jq empty dist/logs/your-file.json`
`Template not found`	Template name mismatch	List templates: `ls -1 dist/TEMPLATES/*.txt`
`gh: command not found`	GitHub CLI not installed	Install: `brew install gh` (macOS) or see GitHub CLI docs
`gh auth required`	Not authenticated with GitHub	Run: `gh auth login`
`Scan hangs or times out`	Large codebase or slow disk	Use `--exclude-pattern` to skip vendor/node_modules

AI Triage Data Missing from HTML Report

Symptom: HTML report generated but doesn't show AI triage summary, false positives, or confidence levels.

Root Cause: HTML was regenerated BEFORE AI triage was performed, or HTML was not regenerated AFTER triage updated the JSON.

Solution:

Verify AI triage data exists in JSON:
```
jq '.ai_triage' dist/logs/[TIMESTAMP].json
```
- If output is null → AI triage hasn't been performed yet
- If output shows triage data → JSON is correct, HTML needs regeneration

Regenerate HTML after triage:

python3 dist/bin/json-to-html.py dist/logs/[TIMESTAMP].json dist/reports/[TIMESTAMP].html

Verify AI triage is now in HTML:
```
grep -c 'AI Triage\|False Positives\|Needs Review' dist/reports/[TIMESTAMP].html
```
- Should return a count > 0
- If 0, check that JSON has ai_triage section

Open HTML in browser:

open dist/reports/[TIMESTAMP].html  # macOS
xdg-open dist/reports/[TIMESTAMP].html  # Linux

Prevention: Always follow the correct sequence:

Run scan → JSON created
Perform AI triage → JSON updated with ai_triage section
Regenerate HTML → HTML includes AI summary
Create GitHub issue → Issue includes AI classifications

Remember: The HTML converter reads the JSON file at the time it runs. If you regenerate HTML before updating the JSON with AI triage data, the HTML will not include the triage information.

AI Triage Hallucinations: Recommendations for Non-Existent Issues

Symptom: AI triage recommendations mention issues (e.g., "Remove debugger statements") that don't appear in the actual findings list.

Root Cause: The AI triage script was generating hardcoded recommendations that didn't validate against actual findings. This has been fixed in v1.1+.

How to Detect:

Review the recommendations in the HTML report
Search the findings list for the recommended issue
If no findings match the recommendation → it's a hallucination

Example (Fixed in v1.1):

❌ OLD (v1.0): Recommendation: "Remove debugger; statements from shipped JS"
   But: Zero findings for debugger statements in the scan

✅ NEW (v1.1): Only recommendations for issues actually found in triaged findings

Prevention (v1.1+):

AI triage now builds recommendations dynamically from actual findings
Each recommendation is validated against the triaged findings set
Validation step logs: ✅ Validation passed: N recommendations match actual findings
If no actionable findings exist, a generic guidance recommendation is provided instead

For AI Agents (v1.1+):

The script automatically validates recommendations before writing JSON
Look for this log message: [AI Triage] ✅ Validation passed: N recommendations match actual findings
If you see warnings about mismatched recommendations, investigate the triaged findings
Never manually add hardcoded recommendations; always derive them from actual findings

If You Encounter Hallucinations:

Check the AI triage script version: grep "version.*:" dist/bin/ai-triage.py | head -1
If version < 1.1, update the script from the main branch
Re-run triage: python3 dist/bin/ai-triage.py dist/logs/[TIMESTAMP].json
Verify recommendations: jq '.ai_triage.recommendations' dist/logs/[TIMESTAMP].json

Getting Help

If you encounter issues not covered here:

Check the logs: dist/logs/[TIMESTAMP].json contains detailed error messages
Validate JSON: Use jq to check for syntax errors
Review README: Main README has additional troubleshooting
GitHub Issues: Report bugs

Quick Reference for AI Agents

Phase Checklist

Phase 1a: Check Templates

List existing templates: ls -1 dist/TEMPLATES/*.txt
Try name variations (exact, lowercase, hyphens, no-hyphens)
If found, skip to Phase 1c

Phase 1b: Complete Template

Read user's template file for path
Find main plugin/theme file
Extract Plugin Name and Version from headers
Detect GitHub repo (optional, don't guess)
Generate complete template using structure from _TEMPLATE.txt
Use lowercase-with-hyphens naming convention

Phase 1c: Run Scan

Execute: dist/bin/run [template-name]
Wait for completion (1-2 minutes typical)
Verify JSON log created: dist/logs/[TIMESTAMP].json
Verify HTML report created: dist/reports/[TIMESTAMP].html

Phase 2: AI Triage ⚠️ CRITICAL: HTML regeneration must happen AFTER triage

Phase 3: GitHub Issue

Determine scan ID from JSON filename
Run: dist/bin/create-github-issue.sh --scan-id [TIMESTAMP]
If no repo: Issue body saved to dist/issues/GH-issue-[TIMESTAMP].md
If repo specified: GitHub issue created automatically
Verify issue includes confirmed findings and needs-review sections

End-to-End Execution

When user says "Run [name] end to end":

# 1. Run scan
dist/bin/run [template-name]

# 2. Extract scan ID from output or find latest JSON
scan_id=$(ls -t dist/logs/*.json | head -1 | xargs basename | sed 's/.json//')

# 3. Perform AI triage (read JSON, analyze, update with ai_triage section)
# [AI agent performs analysis and updates JSON]

# 4. Regenerate HTML with AI summary
python3 dist/bin/json-to-html.py dist/logs/${scan_id}.json dist/reports/${scan_id}.html

# 5. Create GitHub issue
dist/bin/create-github-issue.sh --scan-id ${scan_id}

Key File Locations

File Type	Location	Purpose
Templates	`dist/TEMPLATES/*.txt`	Scan configurations
JSON Logs	`dist/logs/[TIMESTAMP].json`	Machine-readable scan data
HTML Reports	`dist/reports/[TIMESTAMP].html`	Human-readable reports
Issue Bodies	`dist/issues/GH-issue-[TIMESTAMP].md`	GitHub issue markdown
Template Guide	`dist/HOWTO-TEMPLATES.md`	Manual template creation
Main README	`README.md`	User-facing documentation

Cross-Reference Map

Topic	AI Instructions Section	README Section
Template creation	Phase 1b	Project Templates
Running scans	Phase 1c	Quick Start
AI triage	Phase 2	AI-Assisted Triage
GitHub issues	Phase 3	GitHub Issue Creation
False positives	Common Patterns	Quick Scanner
JSON to HTML	Manual Conversion	Tools Included

Document Version: 2.0 Last Updated: 2026-01-13 Maintained By: Hypercart Dev Tools

FilesExpand file tree

_AI_INSTRUCTIONS.md

Latest commit

History

_AI_INSTRUCTIONS.md

File metadata and controls

AI Agent Instructions for WP Code Check

Overview

End-to-End Execution Mode

⚠️ CRITICAL: Orchestration Sequence

Phase 1a: Check for Existing Templates

Template Naming Best Practices

Template Detection Logic

Phase 1b: Template Completion (If Needed)

When to Complete a Template

Steps to Complete a Template

Important Notes

Phase 1c: Running Scans

How Users Should Ask the AI Agent

AI Agent: How to Run Templates

Using Direct Paths (If No Template Exists)

Output Locations

Phase 2: AI-Assisted Triage

When to Use

HTML Report Layout

Workflow Steps

Summary Stats

Confidence Levels

Phase 3: GitHub Issue Creation

When to Use

Prerequisites

Workflow Steps

Output Locations

GitHub Issue Format

Error Handling

Best Practices

Common False Positive Patterns

Manual JSON to HTML Conversion

Troubleshooting

Common Errors and Solutions

AI Triage Data Missing from HTML Report

AI Triage Hallucinations: Recommendations for Non-Existent Issues

Getting Help

Quick Reference for AI Agents

Phase Checklist

End-to-End Execution

Key File Locations

Cross-Reference Map