@vfarcic/dot-ai 0.43.0 → 0.45.0

package/prompts/doc-testing-test-section.md

@@ -2,7 +2,33 @@
 
 You are testing a specific section of documentation to validate both functionality AND accuracy. You must verify that instructions work AND that the documentation text truthfully describes what actually happens.
 
-**Important**: Skip content that has ignore comments containing "dotai-ignore" (e.g., `<!-- dotai-ignore -->`, `.. dotai-ignore`, `// dotai-ignore`). Do not generate issues or recommendations for ignored content.
+**Important**: 
+- Skip content that has ignore comments containing "dotai-ignore" (e.g., `<!-- dotai-ignore -->`, `.. dotai-ignore`, `// dotai-ignore`). Do not generate issues or recommendations for ignored content.
+- Look for testing hints in comments containing "dotai-test-hint" (e.g., `<!-- dotai-test-hint: use mcp__dot-ai__prompts to verify slash commands -->`, `.. dotai-test-hint: run command X to test claim Y`, `// dotai-test-hint: check actual behavior with tool Z`). Follow these hints when testing the associated content.
+
+## CRITICAL MINDSET: User Behavior Simulation
+
+**You are simulating a real user following this documentation step-by-step.**
+
+### User Journey Testing Requirements
+
+**Follow documented workflows exactly as users would:**
+- If docs say "Run this command to test" → Actually execute that command and verify it works
+- If docs say "Navigate to Settings page" → Verify that page/option exists and is accessible  
+- If docs say "You should see output X" → Confirm you actually get output X
+- If docs say "Click the Install button" → Verify that button exists and functions
+- If docs say "This will automatically happen" → Test that it actually happens automatically
+
+**Key User Scenarios to Simulate:**
+1. **Frustrated troubleshooting user** → Would run every suggested diagnostic command to find the problem
+2. **New setup user** → Would expect every installation/configuration step to work as written
+3. **Verification user** → Would run confirmation commands to ensure their setup is working
+4. **Integration user** → Would follow workflow examples expecting them to produce stated results
+
+**Critical Testing Mindset Shifts:**
+- **From**: "This looks like an example command" → **To**: "A user would actually run this - does it work?"
+- **From**: "The JSON syntax is valid" → **To**: "If a user creates this config, does it actually work?"
+- **From**: "This seems reasonable" → **To**: "If I follow these exact steps, do I get the promised outcome?"
 
 ## Section to Test
 **File**: {filePath}
@@ -13,186 +39,46 @@ You are testing a specific section of documentation to validate both functionali
 ## Your Task - Two-Phase Validation
 
 ### Phase 1: Execute and Test (Functional Validation)
-**Goal**: Verify that instructions, examples, and procedures actually work
-
-Execute everything testable in this section:
+Execute everything testable as a real user would:
 - Follow step-by-step instructions exactly as written
-- Execute commands, code examples, or procedures
-- Test interactive elements (buttons, forms, interfaces)
-- Verify file operations, downloads, installations
-- Check that prerequisites are sufficient
+- Execute commands, code examples, procedures (adapt for safety: use `./tmp/` for file operations, test endpoints for URLs, etc.)
+- Test interactive elements and verify file operations work
 - Validate that examples produce expected results
 
 ### Phase 2: Analyze Claims vs Reality (Semantic Validation)  
-**Goal**: Verify that the documentation text truthfully describes what actually happens
-
-**MANDATORY SEMANTIC ANALYSIS** - Check every claim in the documentation:
-
-□ **Difficulty Claims**: Does "easy," "simple," "straightforward" match actual complexity?
-□ **Automation Claims**: Does "automatically," "seamlessly," "instantly" match real behavior?  
+Check every claim in the documentation:
+□ **Difficulty/Time Claims**: Does "easy," "simple," "quickly," "automatically" match reality?
 □ **Outcome Claims**: Do "you will see," "this enables," "results in" match what actually happens?
-□ **Time Claims**: Do "quickly," "immediately," "in seconds" match actual duration?
 □ **Prerequisite Claims**: Are stated requirements actually sufficient for success?
-□ **Success Claims**: Do "successful," "working," "ready" match actual end states?
 □ **User Experience Claims**: Would a typical user get the promised experience?
-□ **Code/Architecture Claims**: When documentation makes claims about code, files, or system architecture, validate them against the actual codebase
-
-### Cross-File Terminology Validation (When Applicable)
-
-**When testing documentation that references related files**, validate terminology consistency:
-
-#### Terminology Consistency Check
-**For files that are part of a documentation set** (e.g., setup guides, user guides, API references):
-
-1. **Identify Key Terms**: Extract important technical terms, feature names, and concepts from current section
-2. **Find Related Files**: Identify documentation files that should use consistent terminology
-3. **Cross-Reference Validation**: Check if the same concepts use identical terms across files
-4. **Flag Inconsistencies**: Report terminology mismatches that could confuse users
-
-**Common Terminology Issues:**
-- Same feature called different names in different files
-- Inconsistent capitalization (e.g., "MCP Server" vs "mcp server") 
-- Different terms for same concept (e.g., "slash commands" vs "command shortcuts")
-- Inconsistent format examples (e.g., `/dot-ai:name` vs `/mcp.dot-ai.name`)
-
-**How to Perform Cross-File Validation:**
-1. **Extract key terms** from current section being tested
-2. **Read related documentation files** mentioned in cross-references or logically related
-3. **Compare terminology usage** across files for consistency
-4. **Report discrepancies** that would confuse users navigating between files
-
-### Code Analysis Validation (When Applicable)
-
-**When testing technical documentation in a code repository**, perform BOTH directions of validation:
-
-#### 1. Validate Documented Claims Against Code
-**File & Directory Claims:**
-- Check if claimed file paths actually exist (e.g., "src/core/discovery.ts")
-- Verify directory structure matches documentation claims
-- Validate that referenced configuration files exist where claimed
-
-**Component & Feature Claims:**
-- For architecture docs claiming "System has components A, B, C" - read the actual source code
-- Check if documented components/classes/functions actually exist in the codebase
-- Verify CLI commands exist if documentation claims they're available
-
-**Implementation Status Claims:**
-- For status markers (✅ IMPLEMENTED, 🔴 PLANNED) - verify against actual code
-- Check if "planned" features are already implemented but not updated in docs
-
-#### 2. Find Missing Documentation (Reverse Analysis)
-**Scan codebase to identify undocumented features:**
-- Read key source directories (src/, lib/, bin/, tools/) to find major components
-- Check package.json, CLI entry points, and main modules for implemented features
-- Look for significant classes, services, interfaces, or tools not mentioned in documentation
-- Identify recently added features that may not be reflected in architecture docs
-
-**For architecture/system documentation specifically:**
-- Compare documented system components against actual code organization
-- Look for major implemented subsystems missing from architecture diagrams
-- Check if all main interfaces/entry points are documented
-
-**How to Perform Code Analysis:**
-1. **Forward validation**: For each documented claim, verify against actual code
-2. **Reverse validation**: Scan actual code to find major features missing from docs
-3. Use file reading tools to examine source code structure
-4. Focus on major components that users would need to know about
-5. Don't flag internal implementation details - focus on user-facing or architecturally significant features
-
-**For each code-related validation, ask:**
-- Does this documented claim match the actual code?
-- Are there major implemented features missing from this documentation section?
-- Would a developer/user be surprised by significant undocumented functionality?
-
-## Universal Testing Approach
-
-### Content Discovery
-Look for any testable content in this section:
-- **Commands/Scripts**: Terminal commands, code snippets, shell scripts
-- **Interactive Steps**: Click buttons, fill forms, navigate interfaces  
-- **File Operations**: Create, modify, download, upload files
-- **Web Interactions**: Visit URLs, test API endpoints, verify web content
-- **Installation Procedures**: Software setup, dependency installation
-- **Configuration Steps**: Settings, environment setup, account creation
-- **Verification Steps**: Commands or actions that check if something worked
-- **Code Examples**: Runnable code that should produce specific outputs
-- **Troubleshooting**: Problem-solution pairs that can be validated
-
-### Universal Functional Testing
-For any instruction found:
-1. **Execute with adaptation** - Modify the steps to work safely in your current environment
-2. **Verify actual outcomes** - Confirm the steps produce the described results
-3. **Complete missing context** - Add authentication, permissions, dependencies, or setup as needed
-4. **Test in safe isolation** - Use temporary directories, test accounts, or sandboxed environments
-5. **Validate end-to-end** - Ensure the full workflow achieves its stated purpose
-
-### Universal Semantic Validation
-For every claim or description:
-1. **Accuracy**: Is the statement factually correct?
-2. **Completeness**: Are there undocumented requirements or side effects?
-3. **Precision**: Do vague terms like "automatically," "easily," "quickly" match reality?
-4. **Outcome matching**: Do results match what's promised?
-5. **User expectations**: Would following this meet the set expectations?
-
-## Validation Patterns
-
-### Pattern 1: Command/Code Claims
-**Documentation Pattern**: "Run X to do Y"
-- **Functional**: Execute command X (adapting for your environment) - does it run without errors?
-- **Semantic**: Does executing command X actually accomplish Y as described?
-
-### Pattern 2: Step-by-Step Procedures  
-**Documentation Pattern**: "Follow these steps to achieve Z"
-- **Functional**: Execute each step (adapting commands/actions for your environment)
-- **Semantic**: Do the executed steps actually lead to achieving Z as described?
-
-### Pattern 3: Interactive Instructions
-**Documentation Pattern**: "Click A, then B will happen"
-- **Functional**: Perform the interaction (click, form submission, navigation, etc.)
-- **Semantic**: Does performing the action actually cause B to happen as claimed?
-
-### Pattern 4: Expected Outputs
-**Documentation Pattern**: "You should see output like: [example]"
-- **Functional**: Execute the process and capture actual output
-- **Semantic**: Does the actual output match the documented example (accounting for environment differences)?
-
-### Pattern 5: Capability Claims
-**Documentation Pattern**: "This feature enables you to X"
-- **Functional**: Use the feature to perform the claimed capability
-- **Semantic**: Does using the feature actually enable X as claimed?
-
-## Execution Guidelines
-
-**PRIMARY GOAL**: Test what users will actually do when following the documentation.
-
-**MANDATORY TESTING APPROACH:**
-1. **Execute documented examples first** - Always prioritize running the actual commands/procedures shown in the documentation
-2. **Use help commands as supplements** - Help commands (`--help`, `man`, `info`) are valuable for understanding syntax or troubleshooting, but should not replace testing documented workflows
-3. **Test real user workflows** - Focus on the actual commands and procedures users are instructed to follow
-
-**Examples of correct approach:**
-- If docs show `npm start` → Execute `npm start` (primary), use `npm --help` if needed for context
-- If docs show `make install PREFIX=/usr/local` → Execute this command (primary), use `make --help` if syntax is unclear
-- If docs show `./configure --enable-feature` → Execute this command (primary), check `./configure --help` if it fails
-- If docs show `pip install -r requirements.txt` → Execute this command (primary), use `pip --help` for troubleshooting
-
-**The key principle**: Test the documented workflows that users will actually follow, using help commands as tools for understanding rather than as substitutes for real testing.
-- **Execute with adaptation**: Modify commands/procedures to work safely in your environment
-  - `npm install -g tool` → `npm install tool` (avoid global installs)
-  - `curl api.prod.com/endpoint` → `curl httpbin.org/get` (use test endpoints)
-  - `mkdir /usr/local/app` → `mkdir ./tmp/test-app` (use local tmp directory)
-  - `cd /path/to/project` → `cd ./tmp/project` (work in local tmp directory)
-- **Create safe contexts**: Use `./tmp/` directory for all file operations and temporary work
-- **Complete incomplete examples**: Add missing parameters, authentication, or setup steps
-  - `curl api.example.com` → `curl -H "Accept: application/json" httpbin.org/json`
-  - `docker run image` → `docker run --rm -it image` (ensure cleanup)
-  - `touch important-file` → `mkdir -p ./tmp && touch ./tmp/important-file` (create in tmp)
-- **Verify actual behavior**: Don't just check syntax - confirm the described outcomes occur
-- **Adapt destructive operations**: Transform dangerous commands into safe equivalents
-  - `rm -rf /data` → `rm -rf ./tmp/test-data` (use local tmp directory)
-  - `sudo systemctl restart service` → `echo "Would restart service"` (simulate when necessary)
-  - Any file creation/modification → redirect to `./tmp/` directory
-- **Document adaptations**: Explain how you modified examples to make them testable
+□ **Feature Claims**: Are described capabilities actually implemented in the codebase?
+□ **Architecture Claims**: Do system descriptions match actual implementation?
+□ **Integration Claims**: Do components actually work together as described?
+□ **Status Claims**: Are features marked as "available" actually working vs. "planned"?
+
+### Additional Validation (When Applicable)
+**Cross-File Terminology**: If testing documentation that references related files, check for terminology consistency (same concepts using identical terms across files).
+
+**Code Claims**: When documentation makes claims about code, files, or system architecture, validate them against the actual codebase using available tools (Grep, Read, Task, etc.).
+
+## Testing Approach
+
+### Functional Testing (Execute Documentation)
+**Execute documented examples first** - Always prioritize running the actual commands/procedures shown in the documentation, adapting for safety when needed. Use help commands only as supplements for understanding, not as substitutes for real testing.
+
+### Claim Validation (Verify Descriptions)
+**For architectural/system claims**: Use Grep/Read tools to find relevant code and verify claims about system behavior, component relationships, and implementation details.
+
+**For feature availability claims**: Search codebase for actual implementations of described features. Distinguish between implemented functionality and planned/aspirational descriptions.
+
+**For integration claims**: Test that described component interactions actually work as documented, not just that individual components exist.
+
+**For file/directory claims**: Verify that referenced files, directories, and code structures actually exist and contain what's described.
+
+**Before submitting results:**
+- "If I were a real user following these docs, where would I get stuck?"
+- "Did I test the actual user workflows, not just validate syntax?"
+- "Would a user following these steps get the experience the docs promise?"
 
 ## Result Format
 
@@ -203,71 +89,37 @@ Return your results as JSON in this exact format:
   "whatWasDone": "Brief summary of what you tested and executed in this section",
   "issues": [
     "Specific problem or issue you found while testing",
-    "Another issue that prevents users from succeeding",
-    "Documentation inaccuracy or missing information"
+    "Another issue that prevents users from succeeding"
   ],
   "recommendations": [
     "Specific actionable suggestion to fix an issue",
-    "Improvement that would help users succeed", 
-    "Way to make documentation more accurate"
+    "Improvement that would help users succeed"
   ]
 }
 ```
 
-**Guidelines for each field:**
-
-**whatWasDone** (string):
-- Concise summary covering BOTH functional testing AND semantic analysis
-- Include what commands/procedures you executed (Phase 1)
-- Include what claims you analyzed (Phase 2)
-- Mention how many items you tested in both phases
-- Example: "Tested 4 installation commands - npm install, API key setup, and 2 verification commands. All executed successfully with minor adaptations. Analyzed 6 documentation claims including 'easy installation' and 'automatic verification' - found installation complexity matches claimed simplicity but verification requires manual interpretation."
-
-**Common Requirements for Both Issues and Recommendations:**
-- **MUST include precise location**: Section headings, specific text snippets, or element descriptions (NOT line numbers)
-- **MUST be immediately actionable**: Clear enough for someone else to locate and address
-- Be specific and actionable items only
-- Do NOT include positive assessments like "section works well" or "documentation is accurate"
-- Use empty arrays if nothing to report
-- Keep each item concise but clear
-- Focus on user impact and success
-
-**issues** (array of strings):
-- **Purpose**: Specific problems that prevent or hinder user success
-- **Include**: Both functional problems (doesn't work) and semantic problems (inaccurate descriptions)
-- **Must explain user impact**: What fails or misleads users
-- Examples: 
-  - "In 'Quick Start' section: npm install command requires global flag but documentation doesn't mention it"
-  - "Under 'Verification' heading: Expected output 'Success: Ready' but actual output shows 'Status: OK'"
-  - "The phrase 'automatically detects' in Prerequisites: Claims automatic detection but requires manual configuration file editing"
-
-**recommendations** (array of strings):
-- **Purpose**: Specific actionable improvements that would help users succeed
-- **Include**: Only concrete changes or additions to the documentation
-- **Must specify exact action**: What text to add, remove, or modify
-- Examples:
-  - "In 'Quick Start' section: Change 'npm install' command to 'npm install --global'"
-  - "Under 'Verification' heading: Update expected output example from 'Success: Ready' to 'Status: OK'"
-  - "In Prerequisites section: Add note after 'automatically detects' phrase: 'Requires manual editing of config.json file before detection works'"
+**Guidelines:**
 
-**Important**: 
-- Use only this JSON format - do not include additional text before or after
-- Arrays can be empty if no issues or recommendations found
-- Keep strings concise but informative
-- Focus on user impact rather than technical details
+**whatWasDone** (string): Concise summary covering BOTH functional testing AND semantic analysis - what commands/procedures you executed and what claims you analyzed.
+
+**issues** (array): CRITICAL PROBLEMS that prevent users from succeeding (broken functionality, incorrect information, missing required steps). Include precise location and explain user impact.
+
+**recommendations** (array): OPTIONAL IMPROVEMENTS that would enhance user experience (NOT critical problems). Must be genuinely optional - user can succeed without these changes. Do NOT repeat anything from issues array.
+
+**ANTI-DUPLICATION RULES**: If something is broken/incorrect → issues only. If something could be enhanced but works fine → recommendations only. Never put the same concept in both arrays.
 
 ## Instructions
 
-**CRITICAL**: You must complete BOTH phases for comprehensive testing:
+Complete BOTH phases for comprehensive testing:
 
 ### Phase 1 Execution Checklist:
-1. **Identify all testable content** - discover commands, procedures, examples
-2. **Execute everything** - run commands, test procedures, verify examples
-3. **Document what actually happens** - capture real outcomes vs expected
+1. Identify all testable content - discover commands, procedures, examples
+2. Execute everything - run commands, test procedures, verify examples  
+3. Document what actually happens - capture real outcomes vs expected
 
 ### Phase 2 Analysis Checklist:  
-1. **Find all claims** - scan text for promises, expectations, descriptions
-2. **Evaluate each claim** - does reality match what's written?
-3. **Check user perspective** - would a typical user get the promised experience?
+1. Find all claims - scan text for promises, expectations, descriptions
+2. Evaluate each claim - does reality match what's written?
+3. Check user perspective - would a typical user get the promised experience?
 
-**Both phases are mandatory** - functional testing without semantic analysis misses critical user experience gaps. Your goal is ensuring users get both working instructions AND accurate expectations about what will actually happen.
+Both phases are mandatory - functional testing without semantic analysis misses critical user experience gaps. Your goal is ensuring users get both working instructions AND accurate expectations about what will actually happen.

package/prompts/resource-selection.md

@@ -8,11 +8,15 @@ You are a Kubernetes expert. Given this user intent and available resources, sel
 ## Available Resources
 {resources}
 
+## Organizational Patterns
+{patterns}
+
 ## Instructions
 
 Select all resources that could be relevant for this intent. Consider:
 - Direct relevance to the user's needs
 - Common Kubernetes patterns and best practices
+- **Organizational patterns** and resource suggestions from your organization's best practices (see above)
 - Resource relationships and combinations
 - Production deployment patterns
 - Complex multi-component solutions

package/prompts/resource-solution-ranking.md

@@ -8,6 +8,11 @@ You are a Kubernetes expert helping to determine which resource(s) best meet a u
 ## Available Resources
 {resources}
 
+## Organizational Patterns
+{patterns}
+
+**Note**: If no organizational patterns are provided above, this means pattern matching is unavailable (Vector DB not configured). Focus on pure Kubernetes resource analysis and recommendations.
+
 ## Instructions
 
 Analyze the user's intent and determine the best solution(s). **Provide multiple alternative approaches** ranked by effectiveness, such as:
@@ -15,6 +20,19 @@ Analyze the user's intent and determine the best solution(s). **Provide multiple
 - A combination of resources that can actually integrate and work together to create a complete solution
 - Different approaches with varying complexity and capabilities
 
+**Organizational Patterns**: Multiple organizational patterns may be provided, each addressing different aspects of the deployment:
+
+- **Generic Application Patterns**: Apply to all applications (networking, monitoring, security)
+- **Architectural Patterns**: Apply to specific architectural styles (stateless, microservice, etc.)  
+- **Infrastructure Patterns**: Apply to specific integrations (database, messaging, etc.)
+- **Operational Patterns**: Apply to specific operational requirements (scaling, schema management, etc.)
+
+**Pattern Composition Strategy**:
+- **Combine relevant patterns** - A single solution can be influenced by multiple patterns
+- **Prioritize by specificity** - More specific patterns should have higher influence than generic ones
+- **Layer pattern guidance** - Generic patterns provide baseline, specific patterns add requirements
+- **Avoid conflicts** - If patterns conflict, prioritize user intent and technical accuracy
+
 **IMPORTANT**: Always provide at least 2-3 different solution alternatives when possible, even if some score lower than others. Users benefit from seeing multiple options to choose from.
 
 ## Validation Requirements
@@ -67,7 +85,24 @@ Analyze the user's intent and determine the best solution(s). **Provide multiple
       "score": 95,
       "description": "Complete application deployment with networking",
       "reasons": ["Provides full application lifecycle", "Includes network access"],
-      "analysis": "Detailed explanation of schema analysis and why this solution meets the user's needs"
+      "analysis": "Detailed explanation of schema analysis and why this solution meets the user's needs",
+      "patternInfluences": [
+        {
+          "patternId": "stateless-app-pattern-123",
+          "description": "Stateless application deployment pattern",
+          "influence": "high",
+          "matchedTriggers": ["stateless app", "web application"],
+          "matchedConcept": "stateless application"
+        },
+        {
+          "patternId": "network-policy-pattern-456", 
+          "description": "Standard networking and security pattern",
+          "influence": "medium",
+          "matchedTriggers": ["application", "deployment"],
+          "matchedConcept": "generic application"
+        }
+      ],
+      "usedPatterns": true
     },
     {
       "type": "single",
@@ -81,10 +116,39 @@ Analyze the user's intent and determine the best solution(s). **Provide multiple
       "score": 75,
       "description": "Basic application deployment",
       "reasons": ["Simple deployment option", "Lower complexity"],
-      "analysis": "Alternative approach with reduced functionality but simpler setup"
+      "analysis": "Alternative approach with reduced functionality but simpler setup",
+      "patternInfluences": [],
+      "usedPatterns": false
     }
   ]
 }
 ```
 
+## Pattern Influence Tracking
+
+For each solution, you MUST include pattern influence information:
+
+**If organizational patterns influenced this solution:**
+- Set `"usedPatterns": true`
+- Include `"patternInfluences"` array with:
+  - `patternId`: Use the pattern's ID from the organizational patterns section
+  - `description`: Brief description of the pattern  
+  - `influence`: Rate as "high", "medium", or "low" based on how much the pattern shaped this solution
+  - `matchedTriggers`: Which pattern triggers matched the user's intent
+
+**If no patterns influenced this solution (or no patterns available):**
+- Set `"usedPatterns": false`
+- Use empty array: `"patternInfluences": []`
+
+**Pattern Influence Guidelines:**
+- **High influence**: Pattern directly suggested these specific resources or architecture
+- **Medium influence**: Pattern informed the approach but didn't dictate specific resources
+- **Low influence**: Pattern provided general guidance but minimal impact on final solution
+
+**Multiple Pattern Handling:**
+- **Include all relevant patterns** that influenced the solution, even if slightly
+- **Use different influence levels** to show relative importance of each pattern
+- **Match concept context** - Reference which deployment concept led to each pattern match
+- **Show composition** - Demonstrate how multiple patterns work together
+
 **IMPORTANT**: In your analysis field, explicitly explain which schema fields enable each requirement from the user intent. If a requirement cannot be fulfilled by available schema fields, explain this and score accordingly.

package/shared-prompts/prd-create.md

@@ -22,6 +22,8 @@ Ask the user to describe the feature idea to understand the core concept and sco
 ### Step 2: Create GitHub Issue FIRST
 Create the GitHub issue immediately to get the issue ID. This ID is required for proper PRD file naming.
 
+**IMPORTANT: Add the "PRD" label to the issue for discoverability.**
+
 ### Step 3: Create PRD File with Correct Naming
 Create the PRD file using the actual GitHub issue ID: `prds/[issue-id]-[feature-name].md`
 
@@ -114,6 +116,8 @@ Work through the PRD template focusing on project management, milestone tracking
 **Priority**: [High/Medium/Low]
 ```
 
+**Don't forget to add the "PRD" label to the issue after creation.**
+
 **Issue Update (after PRD file created):**
 ```markdown
 ## PRD: [Feature Name]

package/shared-prompts/prd-start.md

@@ -18,9 +18,71 @@ You are helping initiate active implementation work on a specific Product Requir
 4. **Identify Starting Point** - Determine the best first implementation task
 5. **Begin Implementation** - Launch into actual development work
 
-## Step 1: PRD Selection
+## Step 0: Context Awareness Check
 
-**Ask the user which PRD they want to start implementing:**
+**FIRST: Check if PRD context is already clear from recent conversation:**
+
+**Skip detection/analysis if recent conversation shows:**
+- **Recent PRD work discussed** - "We just worked on PRD 29", "Just completed PRD update", etc.
+- **Specific PRD mentioned** - "PRD #X", "MCP Prompts PRD", etc.
+- **PRD-specific commands used** - Recent use of `prd-update-progress`, `prd-start` with specific PRD
+- **Clear work context** - Discussion of specific features, tasks, or requirements for a known PRD
+
+**If context is clear:**
+- Skip to Step 2 (PRD Readiness Validation) using the known PRD 
+- Use conversation history to understand current state and recent progress
+- Proceed directly with readiness validation based on known PRD status
+
+**If context is unclear:**
+- Continue to Step 1 (PRD Detection) for full analysis
+
+## Step 1: Smart PRD Detection (Only if Context Unclear)
+
+**Auto-detect the target PRD using these context clues (in priority order):**
+
+1. **Git Branch Analysis** - Check current branch name for PRD patterns:
+   - `feature/prd-12-*` → PRD 12
+   - `prd-13-*` → PRD 13
+   - `feature/prd-*` → Extract PRD number
+
+2. **Recent Git Commits** - Look at recent commit messages for PRD references:
+   - "fix: PRD 12 documentation" → PRD 12
+   - "feat: implement prd-13 features" → PRD 13
+
+3. **Git Status Analysis** - Check modified/staged files for PRD clues:
+   - Modified `prds/12-*.md` → PRD 12
+   - Changes in feature-specific directories
+
+4. **Available PRDs Discovery** - List all PRDs in `prds/` directory:
+   - `prds/12-documentation-testing.md`
+   - `prds/13-cicd-documentation-testing.md`
+
+5. **Fallback to User Choice** - Only if context detection fails, ask user to specify
+
+**PRD Detection Implementation:**
+```bash
+# Use these tools to gather context:
+# 1. Check git branch: gitStatus shows current branch
+# 2. Check git status: Look for modified PRD files  
+# 3. List PRDs: Use LS or Glob to find prds/*.md files
+# 4. Recent commits: Use Bash 'git log --oneline -n 5' for recent context
+```
+
+**Detection Logic:**
+- **High Confidence**: Branch name matches PRD pattern (e.g., `feature/prd-12-documentation-testing`)
+- **Medium Confidence**: Modified PRD files in git status or recent commits mention PRD
+- **Low Confidence**: Multiple PRDs available, use heuristics (most recent, largest)
+- **No Context**: Present available options to user
+
+**Example Detection Outputs:**
+```markdown
+🎯 **Auto-detected PRD 12** (Documentation Testing)
+- Branch: `feature/prd-12-documentation-testing` ✅
+- Modified files: `prds/12-documentation-testing.md` ✅
+- Recent commits mention PRD 12 features ✅
+```
+
+**If context detection fails, ask the user:**
 
 ```markdown
 ## Which PRD would you like to start implementing?
@@ -33,7 +95,10 @@ Execute `dot-ai:prds-get` prompt to see all available PRDs organized by priority
 **Your choice**: [Wait for user input]
 ```
 
-Once the user provides the PRD number, proceed to load and validate that specific PRD.
+**Once PRD is identified:**
+- Read the PRD file from `prds/[issue-id]-[feature-name].md`
+- Analyze completion status across all sections
+- Identify patterns in completed vs remaining work
 
 ## Step 2: PRD Readiness Validation
 

package/shared-prompts/prd-update-progress.md

@@ -13,12 +13,13 @@ You are helping update an existing Product Requirements Document (PRD) based on
 ## Process Overview
 
 1. **Identify Target PRD** - Determine which PRD to update
-2. **Analyze Git Changes** - Review commits and file changes since last update
-3. **Map Changes to PRD Items** - Intelligently connect code changes to requirements
+2. **Context-First Progress Analysis** - Use conversation context first, Git analysis as fallback
+3. **Map Changes to PRD Items** - Intelligently connect work to requirements
 4. **Propose Updates** - Suggest checkbox completions and requirement changes
 5. **User Confirmation** - Verify proposals and handle edge cases
 6. **Update PRD** - Apply changes and add work log entry
 7. **Flag Divergences** - Alert when actual work differs from planned work
+8. **Commit Progress Updates** - Preserve progress checkpoint
 
 ## Step 1: Smart PRD Identification
 
@@ -36,9 +37,23 @@ You are helping update an existing Product Requirements Document (PRD) based on
 - If only one PRD file recently modified → Use that PRD
 - If multiple PRDs possible → Ask user to clarify
 
-## Step 2: Git Change Analysis
+## Step 2: Context-First Progress Analysis
 
-Use git tools to understand what work was completed:
+**PRIORITY: Use conversation context first before Git analysis**
+
+### Conversation Context Analysis (FAST - Use First)
+**If recent conversation shows clear work completion:**
+- **Recently discussed implementations**: "Just completed X", "Implemented Y", "Built Z"
+- **Todo list context**: Check TodoWrite tool for completed/in-progress items
+- **File creation mentions**: "Created file X", "Added Y functionality"
+- **Test completion references**: "Tests passing", "All X tests complete"
+- **User confirmations**: "That works", "Implementation complete", "Ready for next step"
+
+**Use conversation context when available - it's faster and more accurate than Git parsing**
+
+### Git Change Analysis (FALLBACK - Use Only If Context Unclear)
+
+**Only use git tools when conversation context is insufficient:**
 
 ### Commit Analysis
 ```bash
@@ -231,3 +246,34 @@ When applying updates:
 3. **Update status sections** to reflect current phase
 4. **Preserve unchecked items** that still need work
 5. **Update completion percentages** realistically
+
+## Step 8: Commit Progress Updates
+
+After successfully updating the PRD, commit all changes to preserve the progress checkpoint:
+
+### Commit Implementation Work
+```bash
+# MANDATORY: Stage ALL files - implementation work AND PRD updates together
+# DO NOT selectively add only PRD files - commit everything as one atomic unit
+git add .
+
+# Verify what will be committed
+git status
+
+# Create comprehensive commit with PRD reference
+git commit -m "feat(prd-X): implement [brief description of completed work]
+
+- [Brief list of key implementation achievements]
+- Updated PRD checkboxes for completed items
+- Added work log entry with progress summary
+
+Progress: X% complete - [next major milestone]"
+```
+
+### Commit Message Guidelines
+- **Reference PRD number**: Always include `prd-X` in commit message
+- **Descriptive summary**: Brief but clear description of what was implemented
+- **Progress indication**: Include completion status and next steps
+- **Evidence-based**: Only commit when there's actual implementation progress
+
+**Note**: Do NOT push commits unless explicitly requested by the user. Commits preserve local progress checkpoints without affecting remote branches.