Improve Instructions across multiple docs

Author: noelsaw1

CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.4] - 2026-01-13
+
+### Changed
+- **Documentation Improvements** - Enhanced cross-referencing and clarity across all documentation
+  - **README.md:**
+    - Added "end-to-end execution mode" explanation in AI Agent quick start section
+    - Expanded Phase 2 (AI Triage) section with workflow steps and TL;DR format details
+    - Enhanced GitHub Issue Creation section with multi-platform support emphasis
+    - Added cross-references to AI Instructions for detailed workflows
+    - Improved Project Templates section with AI auto-completion features
+    - Added MCP section cross-reference to AI Instructions for triage workflow
+  - **dist/TEMPLATES/_AI_INSTRUCTIONS.md:**
+    - Added workflow decision tree diagram for quick navigation
+    - Added template naming best practices section (lowercase-with-hyphens convention)
+    - Enhanced template detection logic with variation examples
+    - Expanded GitHub repository detection with regex patterns and validation rules
+    - Added "How to Verify" column to false positive patterns table
+    - Enhanced troubleshooting section with common errors and solutions
+    - Added comprehensive "Quick Reference for AI Agents" section with:
+      - Phase-by-phase checklists
+      - End-to-end execution script
+      - Key file locations table
+      - Cross-reference map linking to README sections
+    - Added confidence level guidance for AI triage assessments
+    - Enhanced manual JSON to HTML conversion section with features and troubleshooting
+    - Added multi-platform workflow for GitHub issue bodies (Jira, Linear, Asana, etc.)
+    - Added quick links to related documentation at top of file
+  - **Impact:** AI agents and users can now navigate documentation more efficiently with clear cross-references and decision trees
+
+### Technical Details
+- **Documentation Version:** AI Instructions now at v2.0
+- **Cross-References Added:** 15+ bidirectional links between README and AI Instructions
+- **New Sections:** 8 new subsections in AI Instructions for improved clarity
+- **Tables Enhanced:** 6 tables expanded with additional columns and examples
+
 ## [1.3.3] - 2026-01-13
 
 ### Added

PROJECT/3-COMPLETED/DOCUMENTATION-CROSS-REFERENCE-IMPROVEMENTS.md

@@ -0,0 +1,165 @@
+# Documentation Cross-Reference Improvements
+
+**Created:** 2026-01-13  
+**Completed:** 2026-01-13  
+**Status:** ✅ Completed  
+**Version:** 1.3.4
+
+## Summary
+
+Enhanced cross-referencing and clarity across README.md and AI Instructions to improve navigation and usability for both AI agents and human users.
+
+## Implementation
+
+### Files Modified
+
+1. **README.md** - 5 sections enhanced with cross-references
+2. **dist/TEMPLATES/_AI_INSTRUCTIONS.md** - Major expansion with 8+ new subsections
+3. **CHANGELOG.md** - Documented changes in v1.3.4
+
+### README.md Improvements
+
+#### 1. AI Agent Quick Start Section (Lines 24-36)
+**Before:** Basic 2-step instructions  
+**After:** 3-step workflow with phase breakdown and link to AI Instructions
+
+**Added:**
+- End-to-end execution mode mention
+- Phase 1/2/3 overview
+- Direct link to complete workflow
+
+#### 2. Project Templates Section (Lines 141-158)
+**Before:** Basic template usage  
+**After:** AI agent features highlighted with cross-references
+
+**Added:**
+- Auto-completion feature
+- Template variations handling
+- GitHub integration mention
+- Links to both manual guide and AI instructions
+
+#### 3. Phase 2: AI-Assisted Triage (Lines 155-180)
+**Before:** Basic feature list  
+**After:** Complete workflow with TL;DR format explanation
+
+**Added:**
+- Workflow steps (4-step process)
+- TL;DR format mention
+- Cross-reference to AI Instructions Phase 2
+
+#### 4. GitHub Issue Creation (Lines 182-214)
+**Before:** Basic usage examples  
+**After:** Multi-platform support emphasized
+
+**Added:**
+- Multi-platform support feature
+- Graceful degradation explanation
+- Cross-reference to AI Instructions Phase 3
+
+#### 5. MCP Section (Lines 272-281)
+**Before:** AI agent instructions only  
+**After:** Link to complete triage workflow
+
+**Added:**
+- Cross-reference to AI Instructions for triage workflow
+
+### AI Instructions Improvements
+
+#### 1. Quick Links Section (Lines 1-7)
+**New:** Added navigation links to related docs
+- Main README
+- Template Guide
+- MCP Documentation
+
+#### 2. Workflow Decision Tree (Lines 20-33)
+**New:** Visual decision tree for common user requests
+- End-to-end execution
+- Scan only
+- Template completion
+- Triage only
+- Issue creation only
+
+#### 3. Template Naming Best Practices (Lines 75-111)
+**New:** Complete naming convention guide
+- Recommended vs. acceptable vs. avoid table
+- Rationale for lowercase-with-hyphens
+- Template detection logic with variations
+- Example search order
+
+#### 4. Enhanced GitHub Repo Detection (Lines 143-212)
+**Expanded:** From 9 lines to 70 lines
+- Method 1: Plugin/Theme headers with examples
+- Method 2: README files with grep commands
+- Method 3: Git remote with extraction patterns
+- Regex patterns table
+- Validation rules (what NOT to do)
+- Valid vs. invalid detection examples
+
+#### 5. False Positive Patterns Table (Lines 594-611)
+**Enhanced:** Added "How to Verify" column
+- Specific verification steps for each pattern
+- AI agent tips for context analysis
+- Cross-reference to README Quick Scanner section
+
+#### 6. Troubleshooting Section (Lines 654-678)
+**Expanded:** From 5 entries to 9 entries
+- Added likely cause column
+- Platform-specific solutions
+- Links to external resources
+- "Getting Help" subsection
+
+#### 7. Quick Reference for AI Agents (Lines 680-764)
+**New:** Comprehensive 85-line reference section
+- Phase-by-phase checklists (5 phases)
+- End-to-end execution script
+- Key file locations table
+- Cross-reference map (6 topics)
+- Document version and maintenance info
+
+#### 8. Multi-Platform Workflow (Lines 571-590)
+**New:** GitHub issue body reuse guide
+- Copy/paste workflow for Jira, Linear, Asana, Trello
+- Example commands
+
+## Results
+
+### Metrics
+- **Cross-references added:** 15+ bidirectional links
+- **New sections:** 8 major subsections in AI Instructions
+- **Tables enhanced:** 6 tables with additional columns
+- **Documentation version:** AI Instructions now at v2.0
+- **Lines added:** ~150 lines of new content
+
+### User Impact
+- ✅ **Faster navigation** - Users can jump between related sections easily
+- ✅ **Better discoverability** - Features are cross-referenced from multiple entry points
+- ✅ **Clearer workflows** - Decision trees and checklists guide AI agents
+- ✅ **Reduced confusion** - Naming conventions and detection logic clearly documented
+- ✅ **Improved troubleshooting** - Expanded error table with solutions
+
+### AI Agent Impact
+- ✅ **Faster task execution** - Checklists prevent missed steps
+- ✅ **Better template handling** - Clear naming conventions and detection logic
+- ✅ **Accurate triage** - False positive patterns with verification steps
+- ✅ **Error recovery** - Comprehensive troubleshooting guide
+- ✅ **End-to-end automation** - Complete workflow script provided
+
+## Lessons Learned
+
+### What Worked Well
+1. **Bidirectional cross-references** - Users can navigate from either document
+2. **Decision trees** - Visual guides help AI agents choose correct workflow
+3. **Tables with examples** - Concrete examples clarify abstract concepts
+4. **Quick reference section** - Consolidates all key information in one place
+
+### Best Practices Established
+1. **Always link to detailed docs** - README has overview, AI Instructions has details
+2. **Use anchor links** - Enable direct navigation to specific sections
+3. **Provide both manual and AI workflows** - Support different user types
+4. **Include troubleshooting** - Anticipate common errors and provide solutions
+
+## Related
+- [CHANGELOG.md](../../CHANGELOG.md) - Version 1.3.4 entry
+- [README.md](../../README.md) - Main user documentation
+- [AI Instructions](../dist/TEMPLATES/_AI_INSTRUCTIONS.md) - AI agent workflow guide
+

README.md

@@ -26,8 +26,14 @@ If you're using an AI coding assistant (Cursor, GitHub Copilot, Augment, etc.):
 
 1. Open `dist/TEMPLATES/_AI_INSTRUCTIONS.md` in your editor
 2. Ask your AI: **"Please review this document and what can I do with this tool?"**
+3. For automated workflows, ask: **"Run template [name] end to end"**
 
-Your VS Code Agent will guide you through scanning WordPress plugins and themes, creating templates, and interpreting results.
+Your AI agent will guide you through:
+- **Phase 1**: Scanning WordPress plugins/themes (with template auto-completion)
+- **Phase 2**: AI-assisted triage to identify false positives
+- **Phase 3**: Automated GitHub issue creation
+
+See [AI Instructions](dist/TEMPLATES/_AI_INSTRUCTIONS.md) for the complete end-to-end workflow.
 
 ---
 
@@ -137,14 +143,19 @@ Manage technical debt in legacy codebases:
 Save scan configurations for frequently-checked projects:
 
 ```bash
-# Create template
+# Create template (AI agents can auto-complete metadata)
 ./dist/bin/run my-plugin
 
 # Reuse template
 ./dist/bin/run my-plugin
 ```
 
-See [HOWTO-TEMPLATES.md](dist/HOWTO-TEMPLATES.md) for details.
+**AI Agent Features:**
+- ✅ **Auto-completion** - AI extracts plugin name, version, and GitHub repo from headers
+- ✅ **Template Variations** - Handles hyphens, underscores, spaces in filenames
+- ✅ **GitHub Integration** - Optional `GITHUB_REPO` field for automated issue creation
+
+See [HOWTO-TEMPLATES.md](dist/HOWTO-TEMPLATES.md) for manual usage or [AI Instructions - Phase 1b](dist/TEMPLATES/_AI_INSTRUCTIONS.md#phase-1b-template-completion-if-needed) for AI-assisted template creation.
 
 ### 🤖 **Phase 2: AI-Assisted Triage (v1.1 POC)**
 
@@ -163,8 +174,15 @@ Validate findings and identify false positives with AI assistance:
 - ✅ **Confidence Scoring** - Rates overall assessment confidence (high/medium/low)
 - ✅ **Actionable Recommendations** - Prioritized list of issues to fix
 - ✅ **Executive Summary** - 3-5 paragraph narrative for stakeholders
+- ✅ **TL;DR Format** - Summary appears at top of HTML report for quick review
+
+**Workflow:**
+1. Run scan with template: `./dist/bin/run [template-name]`
+2. AI agent analyzes findings and updates JSON with `ai_triage` section
+3. HTML report regenerated with AI summary at top
+4. Optionally create GitHub issue with confirmed findings
 
-See [TEMPLATES/_AI_INSTRUCTIONS.md](dist/TEMPLATES/_AI_INSTRUCTIONS.md) for detailed triage workflow.
+See [AI Instructions - Phase 2](dist/TEMPLATES/_AI_INSTRUCTIONS.md#phase-2-ai-assisted-triage) for detailed triage workflow and common false positive patterns.
 
 ### 🎫 **GitHub Issue Creation**
 
@@ -192,10 +210,13 @@ Automatically create GitHub issues from scan results with AI triage data:
 - ✅ **Interactive Preview** - Review before creating the issue
 - ✅ **Graceful Degradation** - Works without GitHub repo (generates issue body only)
 - ✅ **Persistent Issue Files** - Saves to `dist/issues/` with matching filename pattern for easy manual copy/paste
+- ✅ **Multi-Platform Support** - Use issue bodies in Jira, Linear, Asana, Trello, etc.
 
 **Requirements:**
-- GitHub CLI (`gh`) installed and authenticated (only for creating issues)
-- Scan with AI triage data (`--ai-triage` flag)
+- GitHub CLI (`gh`) installed and authenticated (only for automated creation)
+- Scan with AI triage data (recommended for best results)
+
+See [AI Instructions - Phase 3](dist/TEMPLATES/_AI_INSTRUCTIONS.md#phase-3-github-issue-creation) for complete workflow and error handling.
 
 ### 🔌 **MCP Protocol Support (AI Integration)**
 
@@ -262,6 +283,8 @@ When analyzing WP Code Check results via MCP:
 4. Suggest fixes with code examples
 5. Reference specific file paths and line numbers
 
+For complete AI triage workflow and false positive detection patterns, see [AI Instructions](dist/TEMPLATES/_AI_INSTRUCTIONS.md).
+
 ---
 
 ## 🛠️ Tools Included