From eb711db17db41b5b07f81da759a10da9659ec988 Mon Sep 17 00:00:00 2001 From: marcusquinn <6428977+marcusquinn@users.noreply.github.com> Date: Thu, 17 Apr 2025 04:25:30 +0100 Subject: [PATCH] Add documentation for working in multi-repository workspaces to prevent feature hallucination --- .ai-assistant.md | 28 +++--- .ai-workflows/feature-development.md | 25 ++++++ .ai-workflows/multi-repo-workspace.md | 122 ++++++++++++++++++++++++++ .ai-workflows/readme.md | 1 + .ai-workflows/wiki-documentation.md | 26 ++++++ 5 files changed, 192 insertions(+), 10 deletions(-) create mode 100644 .ai-workflows/multi-repo-workspace.md diff --git a/.ai-assistant.md b/.ai-assistant.md index 9f3745d..8328a52 100644 --- a/.ai-assistant.md +++ b/.ai-assistant.md @@ -2,6 +2,14 @@ This guide helps AI assistants understand the project structure, workflows, and best practices for this repository. +## IMPORTANT: Repository Context + +This workspace may contain multiple repository folders. Always focus ONLY on the current repository you're working in and avoid hallucinating functionality from other repositories in the workspace. + +- **Current Repository**: wp-fix-plugin-does-not-exist-notices +- **Repository Purpose**: Adds missing plugins to your plugins list with a "Remove Notice" action link, allowing you to safely clean up invalid plugin references +- **Repository Scope**: All code changes, documentation, and functionality discussions should be limited to THIS repository only + ## Project Overview - **Plugin Name**: Fix 'Plugin file does not exist' Notices @@ -23,7 +31,6 @@ Detailed workflow documentation is available in the `.ai-workflows/` directory: - **@.ai-workflows/incremental-development.md**: Time-efficient approach for incremental development and testing - **@.ai-workflows/local-env-vars.md**: Local development environment paths and URLs - **@.ai-workflows/release-process.md**: Steps for preparing and publishing releases -- **@.ai-workflows/wiki-documentation.md**: Guidelines for maintaining wiki documentation ## Version Management @@ -109,20 +116,21 @@ AI assistants should maintain a record of developer preferences in **@.ai-workfl This ensures consistency across coding sessions and reduces the need for developers to repeatedly explain their preferences. -## Wiki Documentation +## Avoiding Cross-Repository Confusion -The plugin has a GitHub wiki that is automatically synced from the `.wiki` directory in the repository. When making changes to the codebase, it's important to keep the wiki documentation up-to-date. +When working in a multi-repository workspace, follow these guidelines to avoid confusion: -### Key Principles +1. **Verify Repository Context**: Always check which repository you're currently working in before making any changes or recommendations. -- **Documentation Synchronization**: Ensure that README.md, readme.txt, and wiki documentation are kept in sync -- **Feature Documentation**: Document new features, hooks, and filters in all relevant places -- **Code Structure Documentation**: Update technical documentation when changing code structure -- **Automatic Syncing**: Changes to the `.wiki` directory are automatically synced to the GitHub wiki +2. **Limit Code Search Scope**: When searching for code or functionality, explicitly limit your search to the current repository. -For detailed guidelines on maintaining wiki documentation, see **@.ai-workflows/wiki-documentation.md**. +3. **Don't Assume Features**: Never assume that features present in one repository should be implemented in another. Each repository has its own specific purpose and feature set. -**IMPORTANT**: When updating features, functions, hooks, or code structure, always check if the wiki documentation needs to be updated as well. This ensures that users have access to accurate and up-to-date information. +4. **Repository-Specific Documentation**: Documentation should only reflect the actual features and functionality of the current repository. + +5. **Cross-Repository Inspiration**: If you want to implement a feature inspired by another repository, explicitly mention that it's a new feature being added, not an existing one. + +6. **Verify Before Implementation**: Before implementing or documenting a feature, verify that it actually exists in the current repository by checking the codebase. ## Common Tasks diff --git a/.ai-workflows/feature-development.md b/.ai-workflows/feature-development.md index 8c09b2c..27c92dd 100644 --- a/.ai-workflows/feature-development.md +++ b/.ai-workflows/feature-development.md @@ -150,6 +150,31 @@ If the repository uses pull requests for code review, create a pull request from - Use nonces for form submissions - Use capability checks for user actions +## Working in Multi-Repository Workspaces + +When developing features in a workspace with multiple repositories: + +1. **Verify Repository Context**: + - Confirm you're working in the correct repository before suggesting or implementing features + - Use `pwd` and `git remote -v` to verify the current repository + +2. **Feature Verification**: + - Before implementing a feature, verify it doesn't already exist in the current repository + - Don't assume features from other repositories should be implemented in this one + - Use `codebase-retrieval` to search for existing functionality + +3. **Repository-Specific Implementation**: + - Implement features appropriate for this specific plugin's purpose + - Maintain consistency with the current repository's architecture and coding style + - Don't copy code directly from other repositories without adaptation + +4. **Cross-Repository Inspiration**: + - If implementing a feature inspired by another repository, explicitly note that it's a new feature + - Adapt the feature to fit the current repository's needs and architecture + - Document the inspiration source in code comments + +For detailed guidelines on working in multi-repository workspaces, see **@.ai-workflows/multi-repo-workspace.md**. + ## Feature Types and Implementation Guidelines ### Admin Interface Features diff --git a/.ai-workflows/multi-repo-workspace.md b/.ai-workflows/multi-repo-workspace.md new file mode 100644 index 0000000..dfd3f1b --- /dev/null +++ b/.ai-workflows/multi-repo-workspace.md @@ -0,0 +1,122 @@ +# Working in Multi-Repository Workspaces + +This document provides guidelines for AI assistants working in VSCode/VSCodium workspaces that contain multiple repository folders. + +## Understanding Multi-Repository Workspaces + +In VSCode/VSCodium, developers often create workspaces that include multiple repository folders. This allows them to work on related projects simultaneously or reference code from one project while working on another. + +### Common Workspace Configurations + +1. **Multiple WordPress Plugins**: A workspace containing several WordPress plugin repositories +2. **Plugin and Theme Combinations**: Repositories for both plugins and themes that work together +3. **Reference Repositories**: Including repositories purely for reference or inspiration +4. **Shared Libraries**: Repositories containing shared code used across multiple projects + +## Potential Issues in Multi-Repository Workspaces + +### 1. Feature Hallucination + +The most common issue is "feature hallucination" - assuming that features present in one repository should be implemented in another, or documenting non-existent features based on code seen in other repositories. + +### 2. Cross-Repository Code References + +Referencing or suggesting code patterns from one repository when working on another can lead to inconsistent coding styles and approaches. + +### 3. Documentation Confusion + +Creating documentation that includes features or functionality from other repositories in the workspace. + +### 4. Scope Creep + +Suggesting changes or improvements based on other repositories, leading to scope creep and feature bloat. + +## Best Practices for AI Assistants + +### 1. Repository Verification + +**ALWAYS** verify which repository you're currently working in before: +- Making code suggestions +- Creating or updating documentation +- Discussing features or functionality +- Implementing new features + +### 2. Explicit Code Search Scoping + +When searching for code or functionality: +- Explicitly limit searches to the current repository +- Use repository-specific paths in search queries +- Verify search results are from the current repository before using them + +### 3. Feature Verification Process + +Before documenting or implementing a feature: + +1. **Check the codebase**: Use the codebase-retrieval tool to search for relevant code in the current repository +2. **Verify functionality**: Look for actual implementation, not just references or comments +3. **Check documentation**: Review existing documentation to understand intended functionality +4. **Ask for clarification**: If uncertain, ask the developer to confirm the feature's existence or scope + +### 4. Documentation Guidelines + +When creating or updating documentation: + +1. **Repository-specific content**: Only document features and functionality that exist in the current repository +2. **Verify before documenting**: Check the codebase to confirm features actually exist +3. **Clear boundaries**: Make it clear which repository the documentation applies to +4. **Accurate feature descriptions**: Describe features as they are implemented, not as they might be in other repositories + +### 5. Cross-Repository Inspiration + +When implementing features inspired by other repositories: + +1. **Explicit attribution**: Clearly state that the feature is inspired by another repository +2. **New implementation**: Treat it as a new feature being added, not an existing one +3. **Repository-appropriate adaptation**: Adapt the feature to fit the current repository's architecture and style +4. **Developer confirmation**: Confirm with the developer that adding the feature is appropriate + +## Repository Context Verification Checklist + +Before making significant changes or recommendations, run through this checklist: + +- [ ] Verified current working directory/repository +- [ ] Confirmed repository name and purpose +- [ ] Checked that code searches are limited to current repository +- [ ] Verified features exist in current repository before documenting them +- [ ] Ensured documentation reflects only the current repository's functionality +- [ ] Confirmed that any cross-repository inspiration is clearly marked as new functionality + +## Example Verification Workflow + +1. **Check current repository**: + ``` + pwd + git remote -v + ``` + +2. **Verify feature existence**: + ``` + # Use codebase-retrieval to search for the feature + # Look for actual implementation, not just references + ``` + +3. **Document with clear repository context**: + ``` + # Always include repository name in documentation + # Be specific about which features are included + ``` + +4. **When suggesting new features**: + ``` + # Clearly state if inspired by another repository + # Explain why it's appropriate for the current repository + ``` + +## Handling Repository Switching + +When the developer switches between repositories in the workspace: + +1. **Acknowledge the switch**: Confirm the new repository context +2. **Reset context**: Don't carry over assumptions from the previous repository +3. **Verify new environment**: Check the structure and features of the new repository +4. **Update documentation references**: Ensure you're referencing documentation specific to the new repository diff --git a/.ai-workflows/readme.md b/.ai-workflows/readme.md index 47774c0..6c05206 100644 --- a/.ai-workflows/readme.md +++ b/.ai-workflows/readme.md @@ -12,6 +12,7 @@ This directory contains workflow documentation for AI assistants working with th - **git-workflow.md**: Detailed git workflow and branch management guidelines - **incremental-development.md**: Time-efficient approach for incremental development and testing - **local-env-vars.md**: Local development environment paths and URLs +- **multi-repo-workspace.md**: Guidelines for working in workspaces with multiple repositories - **release-process.md**: Steps for preparing and publishing new releases - **wiki-documentation.md**: Guidelines for maintaining wiki documentation diff --git a/.ai-workflows/wiki-documentation.md b/.ai-workflows/wiki-documentation.md index 7c8be40..bbe9986 100644 --- a/.ai-workflows/wiki-documentation.md +++ b/.ai-workflows/wiki-documentation.md @@ -77,6 +77,32 @@ To ensure consistency across all documentation sources, follow these guidelines: 2. Update the FAQ and troubleshooting sections based on user feedback 3. Add new examples or clarifications based on user questions +## Repository-Specific Documentation + +When working in a multi-repository workspace, it's critical to ensure that wiki documentation accurately reflects the features and functionality of the **current repository only**. + +### Avoiding Cross-Repository Confusion + +1. **Verify Features Before Documenting**: + - Always verify that a feature exists in the current repository before documenting it + - Use `codebase-retrieval` to search for feature implementations + - Check the actual code, not just comments or references + +2. **Repository-Specific Content**: + - Document only features that exist in the current repository + - Don't assume features from other repositories are present in this one + - Be explicit about which repository the documentation applies to + +3. **Feature Inspiration vs. Existing Features**: + - If documenting a feature inspired by another repository but not yet implemented, clearly mark it as a proposed feature + - Don't document features as if they exist when they're only planned or inspired by other repositories + +4. **Cross-Repository References**: + - If referencing functionality from another repository, clearly indicate that it's external + - Use phrases like "unlike Repository X, this plugin does not include..." + +For detailed guidelines on working in multi-repository workspaces, see **@.ai-workflows/multi-repo-workspace.md**. + ## Best Practices ### Content Guidelines