docs: fix and improve copilot-instructions.md by codepuncher · Pull Request #200 · codepuncher/dotfiles

codepuncher · 2026-02-26T23:01:41Z

Overview

Comprehensive analysis, fixes, and major enhancements to copilot-instructions.md based on automated review and user feedback.

Related Tickets & Documents

Initial analysis identified 17 issues (3 critical, 7 medium, 4 low, 3 suggestions)
User feedback requested 8 major improvements for better usability

Changes

Phase 1: Critical Fixes (3 issues)

✅ Fix incorrect line reference (line 258 → 269)
✅ Fix gh pr merge flag syntax (-md → -m -d in 3 locations)
✅ Add --severity=style flag to shellcheck command

Phase 2: Quick Wins (3 issues)

✅ Add safety warning for @production WP CLI usage
✅ Remove duplicate branch deployment section
✅ Fix section numbering (restart for each language)

Phase 3: Low Priority (3 issues)

✅ Expand "After pushing" section with 4 tasks
✅ Clarify has_block() is WordPress function
✅ Improve gh_check_merge alias phrasing

Phase 4: Medium Priority (4 issues)

✅ Consolidate lint check sections for clarity
✅ Expand JS/CSS linting with concrete npm examples
✅ Clarify Bash UPPERCASE variable convention
✅ Standardize Bash formatting instructions

Phase 5: Enhancements

✅ Add table of contents with subsections
✅ Add quick reference section
✅ Include linting cheat sheet
✅ Add branch naming convention reference
✅ Add concrete performance examples

Phase 6: File Split & Revert (Lessons Learned)

❌ Attempted split into 5 focused files (README, quick-reference, git-workflow, code-standards, tools)
❌ FAILED: Copilot CLI only loads single file, doesn't follow relative links
✅ Merged back to single comprehensive file
✅ Kept all improvements from split version

Phase 7: Major Improvements (8 Enhancements)

Table of Contents - Quick navigation with clear hierarchy
Scope & When These Apply - Clarifies applicability (Itineris vs personal projects)
What NOT to Do - Explicit anti-patterns by category
Common Mistakes - 8 real Copilot errors to avoid
Common Task Patterns - 4 complete workflow examples:
- Fix FreshDesk bug (10-step workflow)
- Address PR comments (multiple threads)
- Implement ClickUp feature (multi-phase)
- Emergency hotfix (fast track)
Better Prioritization - Critical rules and workflows first
Project Information - Locations, structure, CI/CD, tools
Examples Throughout - Real-world scenarios with full context

Impact

File evolution:

Original: 409 lines
After Phase 1-5: 507 lines (+98 lines, +24%)
After split attempt: 910 lines across 5 files (BROKEN)
After revert: 545 lines in 1 file (WORKING)
After Phase 7: 897 lines (+352 lines, +65% from revert)

Improvements:

✅ All 16 actionable issues resolved (94% of identified issues)
✅ Added comprehensive navigation and organization
✅ Included real-world workflow examples
✅ Documented common mistakes to prevent repetition
✅ Clarified scope and applicability
✅ Added project-specific information

Lessons learned:

Copilot CLI loads ONLY ~/.copilot/copilot-instructions.md as single file
Relative links to other files are NOT followed
HTML cache at ~/.copilot/copilot-instructions.html must be deleted when updating
Single comprehensive file is correct approach

Testing

[✓] All changes committed across 7 commits on branch 2026-02-26
[✓] No syntax errors in markdown
[✓] All cross-references verified
[✓] Tested in multiple Copilot sessions - instructions load correctly
[✓] Verified custom scripts are now used instead of raw gh api calls
[✓] Symlink working: ~/.copilot/copilot-instructions.md → ~/.dotfiles/shell/copilot-instructions.md

Before/After

Before:

409 lines with some outdated references
Missing critical context about when to apply rules
No workflow examples
Commands scattered throughout
No anti-pattern documentation
Attempted (broken) multi-file split

After:

897 lines, well-organized and navigable
Clear scope and applicability section
4 complete real-world workflow examples
Explicit anti-patterns and common mistakes
Quick reference at top with TOC
Single file that actually works
All improvements from split version preserved

@production

Fix 9 issues identified in comprehensive analysis: Critical fixes: - Fix incorrect line reference (line 258 → 269) - Fix gh pr merge flag syntax (-md → -m -d in 3 locations) - Add --severity=style flag to shellcheck command Quick wins: - Add safety warning for @production WP CLI usage - Remove duplicate branch deployment section - Fix section numbering (restart for each language) Low priority improvements: - Expand "After pushing" section with 4 tasks - Clarify has_block() is WordPress function - Improve gh_check_merge alias phrasing Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Apply medium-priority fixes and enhancements: Content improvements: - Consolidate lint check sections for clarity - Expand JS/CSS linting with concrete npm examples - Clarify Bash UPPERCASE variable convention (note deviation from standard) - Standardise Bash formatting instructions across sections Navigation enhancements: - Add comprehensive table of contents with subsections - Add quick reference section with common commands - Include linting cheat sheet for all languages - Add branch naming convention reference File grew from 411 to 507 lines with improved organisation and discoverability. All critical and medium-priority issues now resolved. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add practical PHP code examples demonstrating: - Conditional preloading with has_block() check - Conditional script enqueuing based on block presence Makes the Performance Best Practices section more actionable with real-world implementation patterns. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Split monolithic 527-line file into 5 focused files for better AI lookup: New structure: - README.md (100 lines) - Main entry, critical rules, navigation - quick-reference.md (170 lines) - Command cheat sheets - git-workflow.md (240 lines) - Git, PR, deployment, code review - code-standards.md (250 lines) - PHP, JS, CSS, Bash standards - tools.md (150 lines) - Scripts, utilities, credentials Benefits: - Faster lookup: Load only relevant file (100-250 lines vs 527) - Better caching: Smaller files fit better in context - Clear scoping: File names indicate exact content - Improved navigation: README with quick links to guides Old file: shell/copilot-instructions.md (527 lines) New directory: shell/copilot-instructions/ (5 files, 910 total lines) Each file is self-contained with cross-references. README serves as main entry point with critical rules always visible. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Make it explicit that PR comment management is a two-step process: 1. Get comments first (to retrieve thread IDs) 2. Use those thread IDs to reply/resolve Changes: - Add 'Workflow Overview' section in tools.md - Add step numbers and explanatory notes - Clarify that thread-id comes from step 1 output - Add workflow summary to quick-reference.md This prevents confusion about where thread IDs come from and makes the command sequence clear. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot CLI only loads the single file at ~/.copilot/copilot-instructions.md and does not follow relative links to other files. The 5-file split broke the instructions - only README.md was loaded, missing all the detailed commands in other files. This reverts to a single comprehensive file containing all content from: - README.md (critical rules, navigation) - quick-reference.md (command cheat sheets) - git-workflow.md (branching, PRs, deployment) - code-standards.md (language-specific rules) - tools.md (scripts, utilities) All improvements from the refactor are preserved: - Fixed critical issues (line refs, commands, flags) - Clearer sections and organization - Concrete examples - Better formatting Symlink updated: ~/.copilot/copilot-instructions.md -> ~/.dotfiles/shell/copilot-instructions.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Added 8 major enhancements: 1. **Table of Contents** - Quick navigation to all sections with clear hierarchy 2. **Scope & When These Apply** - Clarifies when instructions apply: - Itineris WordPress projects vs personal projects - Project structure and locations - Default branch information 3. **What NOT to Do** - Explicit anti-patterns organized by category: - Git & Deployment violations - Code review mistakes - Code standard violations - Testing & production errors 4. **Common Mistakes to Avoid** - 8 real mistakes Copilot has made: - Committing directly to default branch - Using wrong gh command flags (-md vs -m -d) - Forgetting lints, using gh api instead of scripts - Merging without staging verification - Wrong shellcheck severity, multi-file instructions - Forgetting branch naming conventions 5. **Common Task Patterns** - 4 complete workflow examples: - Fix a bug from FreshDesk ticket (full 10-step workflow) - Address PR code review comments (handle multiple threads) - Implement new feature from ClickUp (multi-phase approach) - Emergency hotfix (fast track for critical issues) 6. **Better Prioritization** - Reorganized structure: - Critical rules and anti-patterns at top - Common workflows before detailed standards - Quick reference easily accessible 7. **Project Information** - Added missing details: - Project locations and structure - How to find default branch - Environment details (staging/production) - CI/CD information - Key tools and support systems - Credentials access patterns 8. **Examples Throughout** - Real-world scenarios with complete command sequences showing full context File grew from 545 to 897 lines but much more useful and actionable. All content is searchable and provides concrete guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Added comprehensive guidance for day-to-day operations and troubleshooting: ## 1. Communication Guidelines (60 lines) - When to ask user vs. proceed autonomously - Always ask: ambiguous requirements, destructive ops, security implications - Proceed: clear requirements, standard patterns, safe operations - How to report progress: concise, outcome-focused, avoid over-explanation - Good vs. bad examples of communication patterns ## 2. Security Best Practices (85 lines) - Input sanitization with WordPress functions - Output escaping (context-appropriate) - SQL injection prevention with $wpdb->prepare() - Nonce verification for CSRF protection - Capability checks (never trust roles) - Credential handling (never log, use 1Password CLI) - File upload security ## 3. Conflict Resolution (70 lines) - Git merge conflict resolution workflow - When to ask user vs. resolve automatically - Package dependency conflicts (composer.lock, package-lock.json) - Database migration conflicts - When/how to abort and ask for help ## 4. Database Operations (95 lines) - CRITICAL safety procedures: backup first, test on staging - Safe migration patterns (adding/removing columns, changing data) - WP CLI database commands (search-replace, query, optimize) - Complete migration workflow (local → staging → production) - Rollback procedures ## 5. Rollback Procedures (130 lines) - Emergency rollback steps (revert deployment immediately) - Rollback database migrations (restore from backup, reverse migration) - Rollback code changes (git revert specific commits) - Rollback dependencies (restore package files) - Prevention strategies - Incident communication (during and after) ## 6. Troubleshooting (220 lines) - CI/CD failures: ShellCheck, PHPCS, test timeouts, build errors - Git issues: SSH keys, detached HEAD, merge conflicts, unrelated histories - WP CLI issues: database connection, timeouts, command not found - Deployment issues: staging not updating, production broken - Linting issues: local vs. CI differences, missing tools - Build issues: missing modules, out of memory - Performance issues: slow site, cache problems - When to ask for help (clear guidelines) ## Impact File evolution: - After Phase 7: 897 lines - After Phase 8: 1552 lines (+655 lines, +73%) Now covers complete operational lifecycle: - ✅ Development workflows - ✅ Security requirements - ✅ Database safety - ✅ Emergency procedures - ✅ Common problems and solutions - ✅ Communication patterns These 6 sections address the most common real-world scenarios and provide clear, actionable guidance for handling them safely. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

CRITICAL FIX: Copilot review runs as GitHub Actions workflow that takes 1-3 minutes. Previously instructions told Copilot CLI to merge after CI passes, but before review workflow completed, causing critical bugs to be missed. Root cause analysis: - Copilot review is 'Copilot code review' GitHub Actions workflow - Workflow starts ~5s after PR created, takes 1-3 minutes to complete - CI checks (Lint, etc.) complete in <1 minute - Old instructions merged after CI, before review workflow finished Real examples of the problem: - PR #147: Merged at 43s, review workflow completed at 2m24s - PR #149: Merged at 1m51s, review workflow completed at 3m2s - PR #150: Merged at 6m56s, review workflow completed at 7m5s Solution: - Wait for CI: gh pr checks --watch - Wait for review workflow: Loop checking for review from copilot-pull-request-reviewer bot - Only merge after BOTH complete Updated sections: - Merging to Default Branch (lines 721-817) - Pattern 1: FreshDesk workflow (lines 288-301) - Pattern 2: PR comments workflow (lines 335-347) - Pattern 3: ClickUp feature workflow (lines 396-409) - Complete Workflow section (lines 602-604) - Quick Reference Commands (lines 1308-1318) This prevents PRs from being merged before automated review completes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

CRITICAL: Agent was merging PRs immediately after Copilot review workflow completed, without checking if there were review comments to address. Problem: - Wait for CI ✓ - Wait for Copilot review workflow ✓ - Check for review comments ✗ (MISSING) - Merge immediately (even with unresolved comments) Solution: Added step to check for unresolved comments before merging: gh-pr-get-comments <pr> --resolved=false Updated sections: - Main workflow instructions (lines 785-791) - Common Mistake #9 (lines 238-244) - Pattern 1: FreshDesk workflow (lines 317-322) - Pattern 2: PR comments workflow (lines 370-375) - Pattern 3: ClickUp feature workflow (lines 438-443) - Complete Workflow summary (lines 650-654) - Quick Reference Commands (lines 1342-1348) Now workflow is: 1. Wait for CI 2. Wait for Copilot review workflow 3. Check for review comments 4. Address comments if they exist 5. Only merge after all comments addressed Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Problem: Agent tried to use web_fetch for FreshDesk tickets instead of using the dedicated freshdesk-get-ticket script with authentication. Added comprehensive section "Working with Tickets and Tasks": - Clear guidance to use scripts for FreshDesk/ClickUp URLs - Explanation of why scripts are better (auth, structured data, private access) - Examples showing URL pattern recognition - Workflow for extracting IDs and creating branches Added Common Mistake #5: - Using web_fetch for FreshDesk/ClickUp - Shows correct script usage with examples Updates: - New section after "Scope & When These Apply" (lines 54-103) - Common Mistake #5 added (lines 252-263) - Renumbered mistakes 5-9 to 6-10 This ensures agents recognize ticket URLs and use proper authenticated scripts instead of attempting web scraping. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Added 10 major improvements covering quality, performance, and operations: HIGH PRIORITY (Common Pain Points): 1. **Handling Copilot Review Comments** (60 lines) - Prioritize by severity (security > bugs > quality > style) - Validate accuracy before changing (false positives) - When to address automatically vs ask user - Handling multiple comments and conflicts with requirements 2. **Failed CI After Push** (50 lines) - What to do when CI fails (was missing) - How to fix linting, tests, and build failures locally - When to ask user for help 3. **Post-Merge Production Verification** (65 lines) - Wait for deployment, verify artifacts - Basic smoke tests and monitoring - What to check and when - How to handle issues detected 4. **Squashing Commit History** (60 lines) - When to squash vs preserve commits - Three methods: squash merge, interactive rebase, reset - Default approach guidance MEDIUM PRIORITY (Quality Improvements): 5. **Dependency Update Strategy** (55 lines) - Safe update process - Check changelogs, test thoroughly - Document major updates - When to update vs when not to 6. **Performance Checks** (75 lines) - Database query optimization - Asset size checks - PageSpeed/Lighthouse testing - Query Monitor usage 7. **Accessibility Basics** (85 lines) - Keyboard navigation, screen readers - Semantic HTML, alt text, color contrast - Form labels, WCAG compliance - When to do thorough testing 8. **SEO Considerations** (95 lines) - Meta tags, heading hierarchy - URL structure, structured data - Image optimization, internal linking - Quick SEO checks LOWER PRIORITY (Specific Scenarios): 9. **Incident Communication** (75 lines) - Assess severity (P0/P1/P2) - Who to notify and when - Progress updates during incidents - Post-mortem documentation 10. **Multisite WordPress** (55 lines) - Network-wide vs site-specific changes - Testing on multisite - Deployment considerations TOTAL ADDITIONS: - +675 lines of guidance - File: 1,807 → 2,478 lines (+37% growth) These additions address common quality issues, improve operational procedures, and provide clear guidance for complex scenarios. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

codepuncher and others added 2 commits February 26, 2026 22:52

codepuncher closed this Feb 26, 2026

codepuncher deleted the 2026-02-26 branch February 26, 2026 23:02

codepuncher and others added 5 commits February 26, 2026 23:03

codepuncher reopened this Feb 26, 2026

codepuncher force-pushed the 2026-02-26 branch 3 times, most recently from e7c6063 to 071af98 Compare February 27, 2026 00:34

codepuncher force-pushed the 2026-02-26 branch from 071af98 to 6820880 Compare February 27, 2026 00:36

codepuncher and others added 3 commits February 27, 2026 09:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: fix and improve copilot-instructions.md#200

docs: fix and improve copilot-instructions.md#200
codepuncher wants to merge 12 commits intomasterfrom
2026-02-26

codepuncher commented Feb 26, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

codepuncher commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Related Tickets & Documents

Changes

Phase 1: Critical Fixes (3 issues)

Phase 2: Quick Wins (3 issues)

Phase 3: Low Priority (3 issues)

Phase 4: Medium Priority (4 issues)

Phase 5: Enhancements

Phase 6: File Split & Revert (Lessons Learned)

Phase 7: Major Improvements (8 Enhancements)

Impact

Testing

Before/After

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

codepuncher commented Feb 26, 2026 •

edited

Loading