feat(discovery): Implement comprehensive devlog discovery feature to prevent duplicate work

Author: tikazyq

.github/copilot-instructions.md

@@ -23,8 +23,8 @@
 This project uses **itself** for development tracking. When working on devlog features, ALWAYS:
 
 ### 1. Use Devlog for All Development Work
-- Create devlog entries for new features, bugs, or improvements using `@devlog/mcp`
-- Use `find_or_create_devlog` to prevent duplicates
+- **Always discover first**: Use `discover_related_devlogs` to find existing relevant work before creating new entries
+- Create devlog entries for new features, bugs, or improvements using `@devlog/mcp` only after thorough discovery
 - Track progress with notes and status updates through the MCP server tools
 
 ### 2. Standard Entry Format
@@ -39,13 +39,15 @@ This project uses **itself** for development tracking. When working on devlog fe
 ```
 
 ### 3. Key Practices
-- **Always check existing entries** before creating new ones using MCP server tools
+- **Always discover first**: Use `discover_related_devlogs` before creating new entries to prevent duplicate work
+- **Review related work**: Analyze discovered entries to build upon existing insights and avoid overlapping efforts
 - **Update progress** as work continues through devlog MCP functions
 - **Document decisions** and technical details in notes using `add_devlog_note`
 - **Use enterprise integrations** when configured via MCP sync functions
 - **Demonstrate new features** by using them through the MCP interface
 
 ### 4. Duplicate Prevention
+- Use `discover_related_devlogs` to thoroughly search for existing relevant work before creating new entries
 - Use `find_or_create_devlog` instead of `create_devlog`
 - Same title + same type = same entry (by design)
 - Different types can have same title (different IDs)
@@ -57,11 +59,12 @@ This project uses **itself** for development tracking. When working on devlog fe
 - **Duplicate Prevention**: Built-in safeguards against creating duplicate entries
 
 ### 6. When Adding New Features
-1. Create devlog entry for the feature using MCP server
-2. Use the feature to track its own development
-3. Update the entry as you implement via MCP functions
-4. Document the feature in the entry notes using MCP tools
-5. Demo the feature by using it through the MCP interface
+1. **Discover first**: Use `discover_related_devlogs` to find existing relevant work
+2. Create devlog entry for the feature using MCP server only if no overlapping work exists
+3. Use the feature to track its own development
+4. Update the entry as you implement via MCP functions
+5. Document the feature in the entry notes using MCP tools
+6. Demo the feature by using it through the MCP interface
 
 This ensures the devlog system is continuously tested and improved through real-world usage.
 

packages/core/src/devlog-manager.ts

@@ -17,6 +17,27 @@ import type {
   EnterpriseIntegration
 } from "@devlog/types";
 
+// Discovery-related interfaces
+export interface DiscoverDevlogsRequest {
+  workDescription: string;
+  workType: DevlogType;
+  keywords?: string[];
+  scope?: string;
+}
+
+export interface DiscoveredDevlogEntry {
+  entry: DevlogEntry;
+  relevance: 'direct-text-match' | 'same-type' | 'keyword-in-notes';
+  matchedTerms: string[];
+}
+
+export interface DiscoveryResult {
+  relatedEntries: DiscoveredDevlogEntry[];
+  activeCount: number;
+  recommendation: string;
+  searchParameters: DiscoverDevlogsRequest;
+}
+
 import { StorageProvider, StorageConfig, StorageProviderFactory } from "./storage/storage-provider.js";
 import { ConfigurationManager } from "./configuration-manager.js";
 
@@ -274,6 +295,121 @@ export class DevlogManager {
     }
   }
 
+  /**
+   * Comprehensively discover related devlog entries before creating new work
+   * Prevents duplicate work by finding relevant historical context
+   */
+  async discoverRelatedDevlogs(request: DiscoverDevlogsRequest): Promise<DiscoveryResult> {
+    await this.ensureInitialized();
+    
+    const { workDescription, workType, keywords = [], scope } = request;
+    
+    // Build comprehensive search terms
+    const searchTerms = [
+      workDescription,
+      workType,
+      scope,
+      ...keywords
+    ].filter(Boolean);
+    
+    // Get all entries for analysis
+    const allEntries = await this.listDevlogs();
+    const relatedEntries: DiscoveredDevlogEntry[] = [];
+    
+    // 1. Direct text matching in title/description/context
+    for (const entry of allEntries) {
+      const entryText = `${entry.title} ${entry.description} ${entry.context.businessContext || ''} ${entry.context.technicalContext || ''}`.toLowerCase();
+      const matchedTerms = searchTerms.filter((term): term is string => 
+        term !== undefined && entryText.includes(term.toLowerCase())
+      );
+      
+      if (matchedTerms.length > 0) {
+        relatedEntries.push({
+          entry,
+          relevance: 'direct-text-match',
+          matchedTerms
+        });
+      }
+    }
+    
+    // 2. Same type entries (if not already included)
+    const sameTypeEntries = allEntries.filter(entry => 
+      entry.type === workType && 
+      !relatedEntries.some(r => r.entry.id === entry.id)
+    );
+    
+    for (const entry of sameTypeEntries) {
+      relatedEntries.push({
+        entry,
+        relevance: 'same-type',
+        matchedTerms: [workType]
+      });
+    }
+    
+    // 3. Keyword matching in notes and decisions
+    for (const entry of allEntries) {
+      if (relatedEntries.some(r => r.entry.id === entry.id)) continue;
+      
+      const noteText = entry.notes.map(n => n.content).join(' ').toLowerCase();
+      const decisionText = entry.context.decisions.map(d => `${d.decision} ${d.rationale}`).join(' ').toLowerCase();
+      const combinedText = `${noteText} ${decisionText}`;
+      
+      const matchedKeywords = keywords.filter((keyword): keyword is string => 
+        keyword !== undefined && combinedText.includes(keyword.toLowerCase())
+      );
+      
+      if (matchedKeywords.length > 0) {
+        relatedEntries.push({
+          entry,
+          relevance: 'keyword-in-notes',
+          matchedTerms: matchedKeywords
+        });
+      }
+    }
+    
+    // Sort by relevance and status priority
+    relatedEntries.sort((a, b) => {
+      type RelevanceType = 'direct-text-match' | 'same-type' | 'keyword-in-notes';
+      
+      const relevanceOrder: Record<RelevanceType, number> = { 
+        'direct-text-match': 0, 
+        'same-type': 1, 
+        'keyword-in-notes': 2 
+      };
+      const statusOrder: Record<DevlogStatus, number> = { 
+        'in-progress': 0, 
+        'review': 1, 
+        'todo': 2, 
+        'testing': 3, 
+        'done': 4,
+        'archived': 5
+      };
+      
+      const relevanceDiff = relevanceOrder[a.relevance as RelevanceType] - relevanceOrder[b.relevance as RelevanceType];
+      if (relevanceDiff !== 0) return relevanceDiff;
+      
+      return statusOrder[a.entry.status] - statusOrder[b.entry.status];
+    });
+    
+    // Calculate active entries and generate recommendation
+    const activeCount = relatedEntries.filter(r => 
+      ['todo', 'in-progress', 'review', 'testing'].includes(r.entry.status)
+    ).length;
+    
+    const recommendation = activeCount > 0 
+      ? `⚠️ RECOMMENDATION: Review ${activeCount} active related entries before creating new work. Consider updating existing entries or coordinating efforts.`
+      : relatedEntries.length > 0
+        ? `✅ RECOMMENDATION: Related entries are completed. Safe to create new devlog entry, but review completed work for insights and patterns.`
+        : `✅ RECOMMENDATION: No related work found. Safe to create new devlog entry.`;
+    
+    return {
+      relatedEntries,
+      activeCount,
+      recommendation,
+      searchParameters: request
+    };
+  }
+
   // Private methods
 
   private async ensureInitialized(): Promise<void> {

packages/core/src/index.ts

@@ -1,4 +1,10 @@
-export { DevlogManager, type DevlogManagerOptions } from "./devlog-manager.js";
+export { 
+  DevlogManager, 
+  type DevlogManagerOptions, 
+  type DiscoverDevlogsRequest, 
+  type DiscoveredDevlogEntry, 
+  type DiscoveryResult 
+} from "./devlog-manager.js";
 export { ConfigurationManager, type DevlogConfig } from "./configuration-manager.js";
 
 // Storage Providers

packages/mcp/src/index.ts

@@ -94,55 +94,31 @@ const tools: Tool[] = [
     },
   },
   {
-    name: "find_or_create_devlog",
-    description: "Find an existing devlog entry by title and type or create a new one if it doesn't exist",
+    name: "discover_related_devlogs",
+    description: "Comprehensively search for existing devlog entries related to planned work before creating new entries. Returns detailed analysis of relevant historical context to prevent duplicate work.",
     inputSchema: {
       type: "object",
       properties: {
-        title: {
+        workDescription: {
           type: "string",
-          description: "Title of the task/feature/bugfix",
+          description: "Detailed description of the work you plan to do",
         },
-        type: {
+        workType: {
           type: "string",
           enum: ["feature", "bugfix", "task", "refactor", "docs"],
-          description: "Type of work being done",
-        },
-        description: {
-          type: "string",
-          description: "Detailed description of the work",
-        },
-        priority: {
-          type: "string",
-          enum: ["low", "medium", "high", "critical"],
-          default: "medium",
-          description: "Priority level",
-        },
-        businessContext: {
-          type: "string",
-          description: "Business context - why this work matters and what problem it solves",
+          description: "Type of work being planned",
         },
-        technicalContext: {
-          type: "string",
-          description: "Technical context - architecture decisions, constraints, assumptions",
-        },
-        acceptanceCriteria: {
+        keywords: {
           type: "array",
           items: { type: "string" },
-          description: "Acceptance criteria or definition of done",
+          description: "Key terms, technologies, components, or concepts involved in the work",
         },
-        initialInsights: {
-          type: "array",
-          items: { type: "string" },
-          description: "Initial insights or knowledge about this work",
-        },
-        relatedPatterns: {
-          type: "array",
-          items: { type: "string" },
-          description: "Related patterns or examples from other projects",
+        scope: {
+          type: "string",
+          description: "Scope or area of the codebase this work affects",
         },
       },
-      required: ["title", "type", "description"],
+      required: ["workDescription", "workType"],
     },
   },
   {
@@ -390,8 +366,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case "create_devlog":
         return await adapter.createDevlog(args as any);
 
-      case "find_or_create_devlog":
-        return await adapter.findOrCreateDevlog(args as any);
+      case "discover_related_devlogs":
+        return await adapter.discoverRelatedDevlogs(args as any);
 
       case "update_devlog":
         return await adapter.updateDevlog(args as any);

packages/mcp/src/mcp-adapter.ts

@@ -4,7 +4,7 @@
 
 import * as crypto from "crypto";
 import { DevlogManager, ConfigurationManager, type DevlogConfig } from "@devlog/core";
-import { DevlogEntry, CreateDevlogRequest, UpdateDevlogRequest } from "@devlog/types";
+import { DevlogEntry, DevlogStatus, DevlogType, CreateDevlogRequest, UpdateDevlogRequest } from "@devlog/types";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 
 export class MCPDevlogAdapter {
@@ -45,23 +45,6 @@ export class MCPDevlogAdapter {
     };
   }
 
-  async findOrCreateDevlog(args: CreateDevlogRequest): Promise<CallToolResult> {
-    await this.ensureInitialized();
-    
-    const entry = await this.devlogManager.findOrCreateDevlog(args);
-    
-    const statusText = entry.createdAt === entry.updatedAt ? "Created" : "Found existing";
-    
-    return {
-      content: [
-        {
-          type: "text",
-          text: `${statusText} devlog entry: ${entry.id}\nTitle: ${entry.title}\nType: ${entry.type}\nPriority: ${entry.priority}\nStatus: ${entry.status}\n\nBusiness Context: ${entry.context.businessContext}\nTechnical Context: ${entry.context.technicalContext}`,
-        },
-      ],
-    };
-  }
-
   async updateDevlog(args: UpdateDevlogRequest): Promise<CallToolResult> {
     await this.ensureInitialized();
 
@@ -371,4 +354,64 @@ export class MCPDevlogAdapter {
       await this.initialize();
     }
   }
+
+  async discoverRelatedDevlogs(args: { 
+    workDescription: string; 
+    workType: DevlogType; 
+    keywords?: string[]; 
+    scope?: string; 
+  }): Promise<CallToolResult> {
+    await this.ensureInitialized();
+    
+    const discoveryResult = await this.devlogManager.discoverRelatedDevlogs(args);
+    
+    if (discoveryResult.relatedEntries.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No related devlog entries found for:\n` +
+                  `Work: ${args.workDescription}\n` +
+                  `Type: ${args.workType}\n` +
+                  `Keywords: ${args.keywords?.join(', ') || 'None'}\n` +
+                  `Scope: ${args.scope || 'N/A'}\n\n` +
+                  `✅ Safe to create a new devlog entry - no overlapping work detected.`,
+          },
+        ],
+      };
+    }
+    
+    // Generate detailed analysis
+    const analysis = discoveryResult.relatedEntries.slice(0, 10).map(({ entry, relevance, matchedTerms }) => {
+      const statusEmoji: Record<DevlogStatus, string> = {
+        'todo': '📋',
+        'in-progress': '🔄',
+        'review': '👀',
+        'testing': '🧪',
+        'done': '✅',
+        'archived': '📦'
+      };
+      
+      return `${statusEmoji[entry.status]} **${entry.title}** (${entry.type})\n` +
+             `   ID: ${entry.id}\n` +
+             `   Status: ${entry.status} | Priority: ${entry.priority}\n` +
+             `   Relevance: ${relevance} (matched: ${matchedTerms.join(', ')})\n` +
+             `   Description: ${entry.description.substring(0, 150)}${entry.description.length > 150 ? '...' : ''}\n` +
+             `   Last Updated: ${new Date(entry.updatedAt).toLocaleDateString()}\n`;
+    }).join('\n');
+    
+    return {
+      content: [
+        {
+          type: "text",
+          text: `## Discovery Analysis for: "${args.workDescription}"\n\n` +
+                `**Search Parameters:**\n` +
+                `- Type: ${args.workType}\n` +
+                `- Keywords: ${args.keywords?.join(', ') || 'None'}\n` +
+                `- Scope: ${args.scope || 'Not specified'}\n\n` +
+                `**Found ${discoveryResult.relatedEntries.length} related entries:**\n\n${analysis}\n\n${discoveryResult.recommendation}`,
+        },
+      ],
+    };
+  }
 }